Adonthell
0.4
|
00001 /* 00002 $Id: prog_rules.dxt,v 1.1 2001/10/15 15:00:06 gnurou Exp $ 00003 00004 Copyright (C) 2001 Alexandre Courbot 00005 Copyright (C) 2001 Kai Sterker 00006 Part of the Adonthell Project http://adonthell.linuxgames.com 00007 00008 This program is free software; you can redistribute it and/or modify 00009 it under the terms of the GNU General Public License. 00010 This program is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY. 00012 00013 See the COPYING file for more details. 00014 */ 00015 00016 /*! 00017 \page page2 Programming rules 00018 00019 \section indent Indentation 00020 No matter who wrote a file, it must be readable by anybody. The beginning of 00021 readability is a correct indentation. Here are a few rules to follow: 00022 00023 \li Block indentation is set to 4 characters. 00024 \li A space should be placed before/after every operator and separator. 00025 \li Air your code. Skip lines between blocks, and don't hesitate to 00026 comment when it is useful. 00027 \li In your classes declarations, make the public interface appear AS SOON 00028 AS POSSIBLE, so users of your class doesn't need to search through the 00029 entire file. 00030 00031 Here is a sample code: 00032 00033 \verbatim 00034 int main (int argc, char * argv []) 00035 { 00036 int i; 00037 00038 for (i = 0; i < 10; i++) 00039 { 00040 int ret = myfunc (0, 1, 2); 00041 if (ret <= 10) return ret; 00042 } 00043 00044 return 0; 00045 } 00046 \endverbatim 00047 00048 \section doxydoc Documentation System 00049 The document you are currently reading is generated by Doxygen from the source 00050 code. Doxygen is a very powerful documentation system that allows programmers 00051 to quickly document their code with class references, diagrams (inheritance, class 00052 hierarchy, ...) and many other useful things with a very small effort, letting 00053 them concentrate on the code rather than the documentation. The programmer documentation 00054 can easily be generated provided the source code (or rather the header files) are 00055 correctly commented. For more informations, have a look at Doxygen's own documentation 00056 which is available at http://www.doxygen.org. 00057 00058 Your classes must all be clearly documented, to allow other developers to use them, 00059 and yourself to remember how they work. You'll have to document at file level, class 00060 level and member level. 00061 00062 \subsection filelev Documenting at file level 00063 EVERY file of Adonthell HAS TO start with the following: 00064 \verbatim 00065 /* 00066 $Id: 00067 00068 Copyright (C) <year> <your name> 00069 Part of the Adonthell Project http://adonthell.linuxgames.com 00070 00071 This program is free software; you can redistribute it and/or modify 00072 it under the terms of the GNU General Public License. 00073 This program is distributed in the hope that it will be useful, 00074 but WITHOUT ANY WARRANTY. 00075 00076 See the COPYING file for more details. 00077 */ 00078 00079 00080 /** 00081 * @file <filename> 00082 * @author <yourname> <<your_email@adress>> 00083 * 00084 * @brief <Briefly describe what's in this file> 00085 * 00086 * 00087 */ 00088 \endverbatim 00089 00090 The first block is for Copyright issues. You clearly show that this file is 00091 distributed under the terms of the GPL ; that it comes with no warranty and 00092 that you are the copyright holder of the file. The Copyright line has to show 00093 all the years this file has been worked on. Several persons may hold 00094 the copyright of a file. In this case, put one Copyright line per person. 00095 The $Id: line is for the CVS system. It will put useful information on this 00096 line when the file will be committed, indicating who last modified this file, 00097 when, and which version number it is. 00098 00099 The second block is for referencing this file into Doxygen's documentation 00100 system. It's quite explicit and MANDATORY if you want to document the classes 00101 in this file. 00102 00103 \subsection classlev Documenting at class level 00104 Each class must have a little documentation block explaining what it does. 00105 Moreover, you can't document a class member if the class itself isn't 00106 documented. Just put a Doxygen block before your class and explain what it is 00107 for: 00108 00109 \verbatim 00110 /** 00111 * This very powerful class blah blah.... 00112 * blah blah blah blah blah 00113 * blah blah blah blah. 00114 * 00115 * @bug Uh, I still have to write the members. 00116 * 00117 */ 00118 class my_very_cool_class 00119 { 00120 ..... 00121 } 00122 \endverbatim 00123 00124 Don't hesitate to use Doxygen's special tags, like \\note or \\bug. 00125 00126 \subsection memblev Documenting at member level 00127 Once your class is briefly described, you can start the "true" documenting, that 00128 is, clearly and precisely describe your public interface. Once again, everything 00129 is better explained in Doxygen's own documentation, but here is an example for 00130 a member function: 00131 00132 \verbatim 00133 class my_class 00134 { 00135 public: 00136 /** 00137 * Returns the square root of the parameter. 00138 * @param a_number Number to calculate the square root of. 00139 * @return Square root of a_number. 00140 */ 00141 float sqrt (float a_number); 00142 } 00143 00144 \endverbatim 00145 00146 Once you have done this, and rebuild the documentation, your class will appear in 00147 the Class Hierarchy diagram, with it's own documentation page and automatically 00148 generated Inheritance Diagram. Have a look at the \link image Image Class Page 00149 \endlink for a sample of the result you can expect, and \link image.h the image.h 00150 file \endlink (see the source code) to see how it has been done. 00151 00152 \section names Method naming 00153 \subsection namgen General naming conventions 00154 There are several different more or less popular ways to name your functions and 00155 classes. Depending on what you like, you can call the same function 00156 perform_something () or PerformSomething (), etc... To keep the interface as clear 00157 and homogeneous as possible, here are a few rules to follow when naming your classes 00158 and functions: 00159 00160 \li Use lower cases, and '_' as a separator if your function name has several words 00161 (ex: perform_something ()). 00162 00163 \li Member access functions should be as short as possible. For read-access, use the 00164 most direct name possible (i.e. length () for the length of an object), for write 00165 access, use set_member style names (set_length (u_int16 l)). Of course, the member 00166 itself should then have a different name than length. Placing an underscore right 00167 after (length_) for naming your member is widely used through the code - but you 00168 are free to do something else if you don't like it. 00169 00170 \li Methods returning something more complicated than a simple %data type (i.e. 00171 functions that returns a pointer to a complex %data structure, etc...) should 00172 use a get_name style instead. For example, a method returning an %image of an 00173 %animation should be named get_image (). 00174 00175 \li If your class is static, the "manual" constructor/destructor should then be named 00176 respectively init () and cleanup (). 00177 00178 Let's see a concrete example of this naming convention through a class interface: 00179 \verbatim 00180 class animation 00181 { 00182 public: 00183 // Constructor 00184 animation (); 00185 00186 // Destructor 00187 ~animation (); 00188 00189 u_int16 length () 00190 { 00191 return length_; 00192 } 00193 00194 u_int16 height () 00195 { 00196 return height_; 00197 } 00198 00199 image * get_image (u_int16 pos) 00200 { 00201 return frame[pos]; 00202 } 00203 00204 ..... 00205 00206 private: 00207 u_int16 length_; 00208 u_int16 height_; 00209 vector <image> frame; 00210 } 00211 \endverbatim 00212 00213 \subsection namcons Constructor selection for Python 00214 As Python can only have one constructor per class, you have to choose 00215 which one will be available. 00216 The default constructor often makes sense ; but if your class requires a 00217 constructor with arguments, then you can transgress this rule of course. 00218 In any case, be aware that you need to be able to reach the state of ANY 00219 of your C++ constructors from Python by using the available constructor 00220 plus one or more of your class methods. 00221 To select which constructor is available, embed the others with a ifndef SWIG 00222 directive. 00223 \verbatim 00224 class image 00225 { 00226 public: 00227 // Default constructor (the one available from Python) 00228 image (); 00229 00230 #ifndef SWIG 00231 // Creates an image of size (l, h) 00232 image (u_int16 l, u_int16 h); 00233 #endif 00234 00235 // This method makes it possible to reach the state of the second constructor 00236 // from Python by doing: im = image (); im.resize (l, h); 00237 // Moreover, it's also useful in other cases. 00238 void resize (u_int16 l, u_int16 h); 00239 ... 00240 }; 00241 \endverbatim 00242 00243 00244 \subsection nampy Making overloaded methods and operators available for Python 00245 SWIG doesn't like overloaded functions and operators, and will print a warning 00246 if it meets one. But the functions or operators you have overloaded have to be 00247 available from the Python interface. To make them available, you should us a 00248 ifdef SWIG directive to declare another inlined function that matches the overloaded 00249 function or operator. An example is better than a long explanation: 00250 \verbatim 00251 class myclass 00252 { 00253 public: 00254 00255 ...... 00256 /** 00257 * Drawing method 1 00258 */ 00259 void draw (int x, int y); 00260 #ifndef SWIG 00261 /** 00262 * Drawing method 2 00263 * @attention Not available from Python. Use draw_part () instead. 00264 * @sa draw_part () 00265 */ 00266 void draw (int x, int y, int l, int h); 00267 #endif 00268 /** 00269 * Synonym of draw (x, y, l, h) to guarantee it's availability from Python. 00270 */ 00271 void draw_part (int x, int y, int l, int h) 00272 { 00273 draw (x, y, l, h); 00274 } 00275 00276 /** 00277 * Copy operator (similar to copy ()). 00278 * 00279 * @attention Not available from Python. Use copy () instead. 00280 * @sa copy () 00281 */ 00282 myclass& operator = (const myclass & src); 00283 00284 /** 00285 * Synonym of operator = to guarantee its access from Python. 00286 * 00287 * @sa operator = 00288 */ 00289 void copy (const myclass& src) 00290 { 00291 *this = src; 00292 } 00293 ... 00294 00295 } 00296 \endverbatim 00297 00298 Don't forget to comment your methods accordingly to their access. 00299 00300 Functions synonym to Operators should have explicit names. As an operator 00301 could have several meanings (+ could be said "add" or "concat", for 00302 example) you are free to choose whatever name fits best with your usage. 00303 00304 \section args Argument passing conventions 00305 00306 \subsection objcts Object passing 00307 Most often you will work with %objects created by yourself or someone else. 00308 Passing such %objects to methods by value has to be absolutely avoided, for 00309 performances and bug issues. Passing a big object by value to a function 00310 requires memory to be allocated for the function's object, and of course the 00311 copy-constructor and destructor to be called. Needless to say, that without 00312 a copy-constructor most complicated %objects won't be correctly passed, and 00313 this is a source of useless bug tracking. 00314 00315 Instead of passing your %objects by value, you'll pass them by reference. 00316 That way, no memory is allocated, and actions are performed directly on your 00317 object. To make it obvious which methods modify the object you're passing 00318 and which don't, the following conventions has been set up: 00319 \li When a function requires an object and doesn't modify it, pass it by 00320 const reference. 00321 \code 00322 void doesntmodify (const myclass & myobject); 00323 \endcode 00324 00325 \li When a function requires an object and modifies it, pass it by address. 00326 \code 00327 void modify (myclass * myobject); 00328 \endcode 00329 00330 \note Of course, this doesn't apply to your operator overloading functions 00331 which are obviously explicit. 00332 00333 And, to make sure nobody will ever pass one of your %objects by value, 00334 declare the copy-constructor as private: 00335 \code 00336 class myclass 00337 { 00338 00339 ... 00340 00341 private: 00342 myclass (myclass & src); 00343 }; 00344 \endcode 00345 This will cause a compilation error if someone ever tries to pass an object 00346 of your class by value. 00347 00348 */