4 Copyright (C) 2001 Alexandre Courbot
5 Copyright (C) 2001 Kai Sterker
6 Part of the Adonthell Project http://adonthell.linuxgames.com
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.
13 See the COPYING file for more details.
17 \page page2 Programming rules
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:
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
31 Here is a sample code:
34 int main (int argc, char * argv [])
38 for (i = 0; i < 10; i++)
40 int ret = myfunc (0, 1, 2);
41 if (ret <= 10) return ret;
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.
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.
62 \subsection filelev Documenting at file level
63 EVERY file of Adonthell HAS TO start with the following:
68 Copyright (C) <year> <your name>
69 Part of the Adonthell Project http://adonthell.linuxgames.com
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.
76 See the COPYING file for more details.
82 * @author <yourname> <<your_email@adress>>
84 * @brief <Briefly describe what's in this file>
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.
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
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
111 * This very powerful class blah blah....
112 * blah blah blah blah blah
113 * blah blah blah blah.
115 * @bug Uh, I still have to write the members.
118 class my_very_cool_class
124 Don't hesitate to use Doxygen's special tags, like \\note or \\bug.
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
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.
141 float sqrt (float a_number);
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.
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
160 \li Use lower cases, and '_' as a separator if your function name has several words
161 (ex: perform_something ()).
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.
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 ().
175 \li If your class is static, the "manual" constructor/destructor should then be named
176 respectively init () and cleanup ().
178 Let's see a concrete example of this naming convention through a class interface:
199 image * get_image (u_int16 pos)
209 vector <image> frame;
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
227 // Default constructor (the one available from Python)
231 // Creates an image of size (l, h)
232 image (u_int16 l, u_int16 h);
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);
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:
259 void draw (int x, int y);
263 * @attention Not available from Python. Use draw_part () instead.
266 void draw (int x, int y, int l, int h);
269 * Synonym of draw (x, y, l, h) to guarantee it's availability from Python.
271 void draw_part (int x, int y, int l, int h)
277 * Copy operator (similar to copy ()).
279 * @attention Not available from Python. Use copy () instead.
282 myclass& operator = (const myclass & src);
285 * Synonym of operator = to guarantee its access from Python.
289 void copy (const myclass& src)
298 Don't forget to comment your methods accordingly to their access.
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.
304 \section args Argument passing conventions
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.
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
322 void doesntmodify (const myclass & myobject);
325 \li When a function requires an object and modifies it, pass it by address.
327 void modify (myclass * myobject);
330 \note Of course, this doesn't apply to your operator overloading functions
331 which are obviously explicit.
333 And, to make sure nobody will ever pass one of your %objects by value,
334 declare the copy-constructor as private:
342 myclass (myclass & src);
345 This will cause a compilation error if someone ever tries to pass an object
346 of your class by value.