Adonthell  0.4
prog_rules.dxt
1 /*
2  $Id$
3 
4  Copyright (C) 2001 Alexandre Courbot
5  Copyright (C) 2001 Kai Sterker
6  Part of the Adonthell Project http://adonthell.linuxgames.com
7 
8  This program is free software; you can redistribute it and/or modify
9  it under the terms of the GNU General Public License.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 /*!
17  \page page2 Programming rules
18 
19  \section indent Indentation
20  No matter who wrote a file, it must be readable by anybody. The beginning of
21  readability is a correct indentation. Here are a few rules to follow:
22 
23  \li Block indentation is set to 4 characters.
24  \li A space should be placed before/after every operator and separator.
25  \li Air your code. Skip lines between blocks, and don't hesitate to
26  comment when it is useful.
27  \li In your classes declarations, make the public interface appear AS SOON
28  AS POSSIBLE, so users of your class doesn't need to search through the
29  entire file.
30 
31  Here is a sample code:
32 
33  \verbatim
34  int main (int argc, char * argv [])
35  {
36  int i;
37 
38  for (i = 0; i < 10; i++)
39  {
40  int ret = myfunc (0, 1, 2);
41  if (ret <= 10) return ret;
42  }
43 
44  return 0;
45  }
46  \endverbatim
47 
48  \section doxydoc Documentation System
49  The document you are currently reading is generated by Doxygen from the source
50  code. Doxygen is a very powerful documentation system that allows programmers
51  to quickly document their code with class references, diagrams (inheritance, class
52  hierarchy, ...) and many other useful things with a very small effort, letting
53  them concentrate on the code rather than the documentation. The programmer documentation
54  can easily be generated provided the source code (or rather the header files) are
55  correctly commented. For more informations, have a look at Doxygen's own documentation
56  which is available at http://www.doxygen.org.
57 
58  Your classes must all be clearly documented, to allow other developers to use them,
59  and yourself to remember how they work. You'll have to document at file level, class
60  level and member level.
61 
62  \subsection filelev Documenting at file level
63  EVERY file of Adonthell HAS TO start with the following:
64  \verbatim
65  /*
66  $Id:
67 
68  Copyright (C) <year> <your name>
69  Part of the Adonthell Project http://adonthell.linuxgames.com
70 
71  This program is free software; you can redistribute it and/or modify
72  it under the terms of the GNU General Public License.
73  This program is distributed in the hope that it will be useful,
74  but WITHOUT ANY WARRANTY.
75 
76  See the COPYING file for more details.
77  */
78 
79 
80 /**
81  * @file <filename>
82  * @author <yourname> <<your_email@adress>>
83  *
84  * @brief <Briefly describe what's in this file>
85  *
86  *
87  */
88  \endverbatim
89 
90  The first block is for Copyright issues. You clearly show that this file is
91  distributed under the terms of the GPL ; that it comes with no warranty and
92  that you are the copyright holder of the file. The Copyright line has to show
93  all the years this file has been worked on. Several persons may hold
94  the copyright of a file. In this case, put one Copyright line per person.
95  The $Id: line is for the CVS system. It will put useful information on this
96  line when the file will be committed, indicating who last modified this file,
97  when, and which version number it is.
98 
99  The second block is for referencing this file into Doxygen's documentation
100  system. It's quite explicit and MANDATORY if you want to document the classes
101  in this file.
102 
103  \subsection classlev Documenting at class level
104  Each class must have a little documentation block explaining what it does.
105  Moreover, you can't document a class member if the class itself isn't
106  documented. Just put a Doxygen block before your class and explain what it is
107  for:
108 
109  \verbatim
110  /**
111  * This very powerful class blah blah....
112  * blah blah blah blah blah
113  * blah blah blah blah.
114  *
115  * @bug Uh, I still have to write the members.
116  *
117  */
118  class my_very_cool_class
119  {
120  .....
121  }
122  \endverbatim
123 
124  Don't hesitate to use Doxygen's special tags, like \\note or \\bug.
125 
126  \subsection memblev Documenting at member level
127  Once your class is briefly described, you can start the "true" documenting, that
128  is, clearly and precisely describe your public interface. Once again, everything
129  is better explained in Doxygen's own documentation, but here is an example for
130  a member function:
131 
132  \verbatim
133  class my_class
134  {
135  public:
136  /**
137  * Returns the square root of the parameter.
138  * @param a_number Number to calculate the square root of.
139  * @return Square root of a_number.
140  */
141  float sqrt (float a_number);
142  }
143 
144  \endverbatim
145 
146  Once you have done this, and rebuild the documentation, your class will appear in
147  the Class Hierarchy diagram, with it's own documentation page and automatically
148  generated Inheritance Diagram. Have a look at the \link image Image Class Page
149  \endlink for a sample of the result you can expect, and \link image.h the image.h
150  file \endlink (see the source code) to see how it has been done.
151 
152  \section names Method naming
153  \subsection namgen General naming conventions
154  There are several different more or less popular ways to name your functions and
155  classes. Depending on what you like, you can call the same function
156  perform_something () or PerformSomething (), etc... To keep the interface as clear
157  and homogeneous as possible, here are a few rules to follow when naming your classes
158  and functions:
159 
160  \li Use lower cases, and '_' as a separator if your function name has several words
161  (ex: perform_something ()).
162 
163  \li Member access functions should be as short as possible. For read-access, use the
164  most direct name possible (i.e. length () for the length of an object), for write
165  access, use set_member style names (set_length (u_int16 l)). Of course, the member
166  itself should then have a different name than length. Placing an underscore right
167  after (length_) for naming your member is widely used through the code - but you
168  are free to do something else if you don't like it.
169 
170  \li Methods returning something more complicated than a simple %data type (i.e.
171  functions that returns a pointer to a complex %data structure, etc...) should
172  use a get_name style instead. For example, a method returning an %image of an
173  %animation should be named get_image ().
174 
175  \li If your class is static, the "manual" constructor/destructor should then be named
176  respectively init () and cleanup ().
177 
178  Let's see a concrete example of this naming convention through a class interface:
179  \verbatim
180  class animation
181  {
182  public:
183  // Constructor
184  animation ();
185 
186  // Destructor
187  ~animation ();
188 
189  u_int16 length ()
190  {
191  return length_;
192  }
193 
194  u_int16 height ()
195  {
196  return height_;
197  }
198 
199  image * get_image (u_int16 pos)
200  {
201  return frame[pos];
202  }
203 
204  .....
205 
206  private:
207  u_int16 length_;
208  u_int16 height_;
209  vector <image> frame;
210  }
211  \endverbatim
212 
213  \subsection namcons Constructor selection for Python
214  As Python can only have one constructor per class, you have to choose
215  which one will be available.
216  The default constructor often makes sense ; but if your class requires a
217  constructor with arguments, then you can transgress this rule of course.
218  In any case, be aware that you need to be able to reach the state of ANY
219  of your C++ constructors from Python by using the available constructor
220  plus one or more of your class methods.
221  To select which constructor is available, embed the others with a ifndef SWIG
222  directive.
223  \verbatim
224  class image
225  {
226  public:
227  // Default constructor (the one available from Python)
228  image ();
229 
230  #ifndef SWIG
231  // Creates an image of size (l, h)
232  image (u_int16 l, u_int16 h);
233  #endif
234 
235  // This method makes it possible to reach the state of the second constructor
236  // from Python by doing: im = image (); im.resize (l, h);
237  // Moreover, it's also useful in other cases.
238  void resize (u_int16 l, u_int16 h);
239  ...
240  };
241  \endverbatim
242 
243 
244  \subsection nampy Making overloaded methods and operators available for Python
245  SWIG doesn't like overloaded functions and operators, and will print a warning
246  if it meets one. But the functions or operators you have overloaded have to be
247  available from the Python interface. To make them available, you should us a
248  ifdef SWIG directive to declare another inlined function that matches the overloaded
249  function or operator. An example is better than a long explanation:
250  \verbatim
251  class myclass
252  {
253  public:
254 
255  ......
256  /**
257  * Drawing method 1
258  */
259  void draw (int x, int y);
260 #ifndef SWIG
261  /**
262  * Drawing method 2
263  * @attention Not available from Python. Use draw_part () instead.
264  * @sa draw_part ()
265  */
266  void draw (int x, int y, int l, int h);
267 #endif
268  /**
269  * Synonym of draw (x, y, l, h) to guarantee it's availability from Python.
270  */
271  void draw_part (int x, int y, int l, int h)
272  {
273  draw (x, y, l, h);
274  }
275 
276  /**
277  * Copy operator (similar to copy ()).
278  *
279  * @attention Not available from Python. Use copy () instead.
280  * @sa copy ()
281  */
282  myclass& operator = (const myclass & src);
283 
284  /**
285  * Synonym of operator = to guarantee its access from Python.
286  *
287  * @sa operator =
288  */
289  void copy (const myclass& src)
290  {
291  *this = src;
292  }
293  ...
294 
295  }
296  \endverbatim
297 
298  Don't forget to comment your methods accordingly to their access.
299 
300  Functions synonym to Operators should have explicit names. As an operator
301  could have several meanings (+ could be said "add" or "concat", for
302  example) you are free to choose whatever name fits best with your usage.
303 
304  \section args Argument passing conventions
305 
306  \subsection objcts Object passing
307  Most often you will work with %objects created by yourself or someone else.
308  Passing such %objects to methods by value has to be absolutely avoided, for
309  performances and bug issues. Passing a big object by value to a function
310  requires memory to be allocated for the function's object, and of course the
311  copy-constructor and destructor to be called. Needless to say, that without
312  a copy-constructor most complicated %objects won't be correctly passed, and
313  this is a source of useless bug tracking.
314 
315  Instead of passing your %objects by value, you'll pass them by reference.
316  That way, no memory is allocated, and actions are performed directly on your
317  object. To make it obvious which methods modify the object you're passing
318  and which don't, the following conventions has been set up:
319  \li When a function requires an object and doesn't modify it, pass it by
320  const reference.
321  \code
322  void doesntmodify (const myclass & myobject);
323  \endcode
324 
325  \li When a function requires an object and modifies it, pass it by address.
326  \code
327  void modify (myclass * myobject);
328  \endcode
329 
330  \note Of course, this doesn't apply to your operator overloading functions
331  which are obviously explicit.
332 
333  And, to make sure nobody will ever pass one of your %objects by value,
334  declare the copy-constructor as private:
335  \code
336  class myclass
337  {
338 
339  ...
340 
341  private:
342  myclass (myclass & src);
343  };
344  \endcode
345  This will cause a compilation error if someone ever tries to pass an object
346  of your class by value.
347 
348  */