doc/conventions.doch

   1 /**
   2  * @page conventions Conventions
   3  *
   4  * @section build_system Build system
   5  * @subsection cmake CMake
   6  * - you should not specify headers to CMake
   7  * - you have to install your libraries in LIBDIR
   8  * - you have to install your binaries in BINDIR
   9  * - you have to install your plugins in PLUGINDIR
  10  *
  11  * @section file_naming File naming
  12  * @subsection composed_names Composed names
  13  * Good: @code my-composed-name.hh my-composed-name.cc @endcode
  14  * @subsection extension Extension
  15  * - .c: C source file
  16  * - .h: C header file
  17  * - .cc: C++ source file (the one we compiles)
  18  * - .hh: C++ header file, this file include the corresponding .hxx
  19  * - .hxx: C++ inline functions
  20  * - .cxx: C++ templates implementation
  21  *
  22  * @subsection rationnales Rationnales
  23  * - When you read headers, you don't want to see the how
  24  * a method is implemented. To keep headers as small as possible,
  25  * inline functions should be in the corresponding .hxx file.
  26  * - We are using C++0x and templates take a lot of time to compile.
  27  * To save time we don't expose functions/methods which are not
  28  * inline. When you define a class which requiere a template. You should
  29  * add:
  30  * @code extern template class MyTemplate<B, A, N, D, E>; @endcode
  31  * in your header (.hh). This says that the template will be compiled
  32  * somewhere and you don't have to do it yourself. Then in your source
  33  * file (.cc), you have to include necessary template implementation (.cxx)
  34  * and tell the compiler to implement the template here:
  35  * @code template class MyTemplate<B, A, N, D, E>; @endcode
  36  *
  37  * @section coding Coding
  38  * - your file should not exceed 80 columns
  39  * - indentation is two spaces
  40  * - you should not use tabs, if you do, ensure that one tab is 8 characters
  41  * - your files must not have trailing whitespaces
  42  * - you should avoid big functions and split you code into small functions
  43  * - ascii art is allowed ;-) but outside of methods/function and class declarations
  44  * - you should use emacs or vim, but not eclipse, or any bloated ide ^^
  45  *
  46  * @code
  47  * #ifndef TETON_HH
  48  * # define TETON_HH
  49  *
  50  * class Fur;
  51  *
  52  * class Teton
  53  * {
  54  * public:
  55  *   Teton();
  56  *   virtual ~Teton();
  57  *
  58  *   inline bool isPointing() const;
  59  *   virtual void titillate();
  60  *
  61  *   typedef std::vector<Fur *> furs_t; // you may provide a typedef for complex types
  62  *   furs_t fur; // public variables should not be prefixed
  63  *
  64  * protected:
  65  *   bool isPointing_; // protected and private variables should be suffixed with `_'
  66  * };
  67  *
  68  * # include "teton.hxx" // inline bool Teton::isPointing() const is defined here
  69  *
  70  * extern template class std::vector<Fur *>; // people don't want to compile code for nothing
  71  *
  72  * #endif /* !TETON_HH */
  73  * @endcode
  74  */