Adonthell 0.4
prog_rules.dxt
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  */