doc/UserDoxygen/CodingStyle.html

   1 <!--
   2 # ---------------------------------------------------------------------
   3 #
   4 # Copyright (c) CREATIS (Centre de Recherche en Acquisition et Traitement de l'Image
   5 #                        pour la Santé)
   6 # Authors : Eduardo Davila, Frederic Cervenansky, Claire Mouton
   7 # Previous Authors : Laurent Guigues, Jean-Pierre Roux
   8 # CreaTools website : www.creatis.insa-lyon.fr/site/fr/creatools_accueil
   9 #
  10 #  This software is governed by the CeCILL-B license under French law and
  11 #  abiding by the rules of distribution of free software. You can  use,
  12 #  modify and/ or redistribute the software under the terms of the CeCILL-B
  13 #  license as circulated by CEA, CNRS and INRIA at the following URL
  14 #  http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
  15 #  or in the file LICENSE.txt.
  16 #
  17 #  As a counterpart to the access to the source code and  rights to copy,
  18 #  modify and redistribute granted by the license, users are provided only
  19 #  with a limited warranty  and the software's author,  the holder of the
  20 #  economic rights,  and the successive licensors  have only  limited
  21 #  liability.
  22 #
  23 #  The fact that you are presently reading this means that you have had
  24 #  knowledge of the CeCILL-B license and that you accept its terms.
  25 # ------------------------------------------------------------------------
  26 -->
  27
  28 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  29 <html><head>
  30    <meta http-equiv="Content-Type"
  31    content="text/html;charset=iso-8859-1"><title>bbtk Developpers</title></head>
  32
  33 <body>
  34
  35 <!--#######################################################################-->
  36 <h1>bbtk coding style (and other religious/agnostic beliefs)</h1>
  37 <hr size="1"><address style=""></address>
  38
  39 <pre>* Introduction:
  40    The following coding style intends to ease the work of developpers
  41    themselves but also of users who will study, maintain, fix, and extend
  42    the code. Any bread crumbs that you can drop in the way of explanatory
  43    names and comments will go a long way towards helping other readers and
  44    developers.
  45    Keep in mind that to a large extent the structure of code directly
  46    expresses its implementation.
  47
  48 * Language:
  49  - C++ (for the kernel) and Python (for the wrappers).
  50  - all the names (variables, members, methods, functions) and comments
  51    should be based on English. Documentation, guides, web site and other
  52    informations should be in English.
  53    Make sure you use correct (basic) English and complete, grammatically
  54    correct sentences for comments and documentation.
  55
  56 * General layout:
  57  - Each line of code should take no more than 79 characters. Break the code
  58    across multiple lines as necessary.
  59  - Methods and functions should keep a reasonable number of lines when
  60    possible (a typical editor displays 50 lines). Avoid code duplication.
  61    Always prefer creating a new method or function to duplication.
  62    A high indentation level generally suggests the need for a new
  63    method or function.
  64  - All the code should be properly indented. The appropriate indentation
  65    level is TWO spaces for each level of indentation. DO NOT USE TABS.
  66    Set up your editor to insert spaces. Using tabs may look good in your
  67    editor but will wreak havoc in others, or in external tools (e.g. side
  68    by side diffs).
  69  - The declaration of variables within classes, methods, and functions
  70    should be one declaration per line. Provide them with default values
  71    and don't rely on compilers for default initialization.
  72
  73 * Naming conventions:
  74  - Generalities:
  75    In general, names are constructed by using case change to indicate
  76    separate words, as in ImageDataSize (standing for "image data size").
  77    Underscores are not used. Variable names are choosen carefully with the
  78    intention to convey the meaning behind the code. Names are generally
  79    spelled out; use of abbreviations is discouraged.
  80    [Note: abbreviation are allowable when in common use, and should be in
  81     uppercase as in LUT or RGBA.]
  82    While this does result in long names, it self-documents the code.
  83  - Naming Files:
  84    Files should have the same name as the class, with a "bbtk" prepended.
  85    Header files are named .h, while implementation files are named either
  86    .cxx or .txx, depending on whether they are implementations of templated
  87    classes. For example, the class bbtk::BlackBox is declared and defined
  88    in the files bbtkBlackBox.h and bbtkBlackBox.cxx.
  89  - Naming Class Data Members, Methods, and Functions:
  90    Class data members (aka Attributes) are named beginning with a lower case 'm'
  91    (m as 'member'!) followed by capital letter as in mGroupPixel, in order not
  92    be confused with methods names.
  93    Global functions and class methods, either static or class members, are
  94    named beginning with a capital letter, as in GetImageDataSize().
  95  - Naming Local Variables:
  96    Local variables begin in lowercase. There is more flexibility in the
  97    naming of local variables although they still should convey some
  98    semantics.
  99  - Naming function parameters:
 100    Function parameters begin in lowercase. There is more flexibility in the
 101    naming of function parameters although they still should convey some
 102    semantics.
 103
 104 * Classes:
 105  - Don't use the inline keyword when defining an inline function
 106    within a class definition.
 107    (Any method defined within a .h file is ipso facto considered as 'inline'.
 108    Dont write useless stuff!)
 109  - As stated in the "Naming conventions" section, class data members
 110    named beginning with a lower case 'm' followed by capital letter
 111    as in mGroupPixel.
 112    But the parameter names of method should be named with a lowercase
 113    letter (in order to distinguish at a glance data members, from parameters
 114    and also to avoid potential collisions with data members):
 115       void A::SetGroupPixel( int groupPixel )
 116       {
 117          mGroupPixel = groupPixel;
 118       }
 119  - Don't use trailing ';' in inline function definition.
 120    use :
 121    void A::SetGroupPixel( int groupPixel ){mGroupPixel = groupPixel;}
 122      NOT
 123    void A::SetGroupPixel( int groupPixel ){mGroupPixel = groupPixel;};
 124  - Do not repeat the 'virtual' keyword when overriding virtual base methods
 125    in declaration of subclasses:
 126      class A
 127      {
 128         virtual void foo(...);
 129      };
 130      class B : public bbtk::A
 131      {
 132         void foo(...);          // and NOT: virtual void foo(...);
 133      };
 134
 135     (when the keyword 'virtual' is used at the parent level, it's propagated
 136      for all the child classes)
 137
 138  - In declaration of subclasses, always preprend the class name with 'bbtk::'
 139    in order not to confuse Umbrello ( OpenSource UML diagram generator)
 140      class A
 141      {
 142         ...
 143      };
 144      class B : public bbtk::A // and NOT: class B: public A
 145      {
 146         ...
 147      };
 148  - The public, protected, private declarations should be at the
 149    same indent level as the class. Use :
 150      class A
 151      {
 152      public:
 153         void bar(...);
 154      protected:
 155         void foo(...);
 156      private:
 157         void pff(...);
 158      };
 159
 160  - The Data members should be declared at the end of the class declaration :
 161      class A
 162      {
 163      public:
 164         void bar(...);
 165      protected:
 166         void foo(...);
 167      private:
 168         void pff(...);
 169
 170      // --- Data members
 171
 172      public:
 173         int mPublicCounter;
 174      protected:
 175         int mProtectedCounter;
 176      private:
 177         int mPrivateCounter;
 178      };
 179
 180  - Method and functions devoided of arguments should not use the void
 181    notation. Use :
 182      SomeType Header::GetPixelData()
 183    and not
 184      SomeType Header::GetPixelData(void)
 185
 186 * Use of braces:
 187  - Braces must be used to delimit the scope of an if, for, while, switch, or
 188    other control structure. Braces are placed on a line by themselves, and
 189    at the same indentation level as the control structure to which they
 190    belong:
 191       for (i=0; * i&lt;3; i++)
 192       {
 193          ...
 194       }
 195    and NOT :
 196       for (i=0; * i&lt;3; i++) {
 197          ...
 198       }
 199    or when using an if:
 200       if ( condition )
 201       {
 202          ...
 203       }
 204       else if ( other condition )
 205       {
 206          ...
 207       }
 208       else
 209       {
 210         ....
 211       }
 212     and NOT :
 213       if ( condition ) {
 214          ...
 215       } else if ( other condition ) {
 216          ...
 217       } else {
 218          ....
 219       }
 220    You can choose to use braces on a line with a code block when
 221    the block consists of a single line:
 222       if ( condition ) { foo=1; }
 223       else if ( condition2 ) { foo=3; }
 224       else { return; }
 225    or
 226       for (i=0; i&lt;3; ++i) {x[i]=0.0;}
 227    Methods and functions should follow the same usage of braces:
 228       void File::ParsePixelData()
 229       {
 230          ...
 231       }
 232
 233 * Special layout:
 234  - Avoid code mixed with comments on a single line. Instead, prepend the
 235    logical blocks of code with the concerned comments.
 236  - Use parentheses around conditions e.g. with an if statement:
 237       if ( someLocalVariable == 2 ) { ... }
 238  - Add spaces around parentheses, or braces. Use
 239       if ( someLocalVariable == 2 ) { mClassMember += 1; }
 240    and not
 241       if (someLocalVariable == 2) {mClassMember += 1;}
 242  - Add spaces around each side of the assignement operator, and
 243    around binary operators used in boolean expression. Use
 244       someLocalVariable = mClassMember * 2;
 245       if ( someLocalVariable == 2 || mClassMember == 2 ) ...
 246    and not
 247       someLocalVariable=mClassMember*2;
 248       if ( someLocalVariable==2||mClassMember==2 ) ...
 249
 250 * Miscelaneous:
 251  - Don't use underscores. Don't use tabs. Don't use control characters
 252    like ^M. Anyhow, cvs is configured to reject such commits.
 253  - Comments should be in C++ style ("// ...", two slashes, per line). Don't
 254    use C style comments ("/* ... */").
 255  - The last line of a file should terminate with "\n".
 256  - Returned arguments of methods and functions should not be wrapped with
 257    parentheses. Use
 258       return iter-&gt;second;
 259    but do not use
 260       return ( iter-&gt;second );
 261
 262 * Debugging and Verbose modes:
 263    Never use std::cout. Instead use the bbtkMessage, bbtkDebugMessage, bbtkWarning or bbtkError macros and their variants. Example:
 264       #include "bbtkMessageManager.h"
 265       ...
 266       {
 267          bbtkDebugMessageInc("MyClass",9,"Local function name: entering.");
 268          ...
 269          bbtkDecTab("MyClass",9);
 270       }
 271     will send the message to std::cout when the Debug messages are compiled
 272     and the Message Level for the category of messages "MyClass" is greater than 9.
 273
 274 * Documentation:
 275    The Doxygen open-source system is used to generate on-line documentation.
 276    Doxygen requires the embedding of simple comments in the code which is in
 277    turn extracted and formatted into documentation. See :
 278       http://www.stack.nl/~dimitri/doxygen/
 279    for more information about Doxygen.
 280  - Documenting a class:
 281    Classes should be documented using the class and brief doxygen commands,
 282    followed by the detailed class description:
 283       /**
 284        * \class Header
 285        * \brief Header acts as container of Dicom elements of an image.
 286        *
 287        * Detailed description of the class is provided here
 288        * ...
 289        */
 290    The key here is that the comment starts with /**, each subsequent line has
 291    an aligned *, and the comment block terminates with a */.
 292  - Documenting class members and inline methods:
 293    All the members and the inline methods should be documented within
 294    the class declaration ( .h file) as shown in the following example:
 295       class Header
 296       {
 297          /// True when parsing was successfull. False otherwise.
 298          bool mReadable = false;
 299
 300          /// \brief The number of lines of the image as interpreted from
 301          ///        the various elements encountered at header parsing.
 302          int mNumberOfLines = -1;
 303
 304          /// Predicate implemented as accessor around \ref mReadable.
 305          bool IsReadable() { return mReadable; }
 306       };
 307  - Documenting a Method:
 308    Methods should be documented using the following comment block style
 309    as shown in the following example:
 310
 311       /**
 312        * \brief  Within the Dicom Elements (parsed with the public and private
 313        *         dictionaries), look for the element value representation of
 314        *         a given tag.
 315        * @param  group  Group number of the searched tag.
 316        * @param  elem Element number of the searched tag.
 317        * @return Corresponding element value representation when it exists,
 318        *         and the string "bbtk::Unfound" otherwise.
 319        */
 320       std::string Document::GetEntryByNumber(guint16 group, guint16 elem)
 321       {
 322          ...
 323       }
 324
 325 * External includes and C style:
 326  - Only the C++ standard library and the STL includes should be used.
 327    When including don't use the .h extension (use #include <iostream>
 328    instead of #include <iostream.h>).
 329    Note: include the stl header AFTER the bbtk ones (otherwise pragma
 330          warnings won't work).
 331  - Don't use the C standard library. Don't include stdio.h, ctype.h...
 332    Don't use printf(), sprinf(), FILE*...
 333  - Don't use the NULL notation (neither as macro, nor as const int NULL=0).
 334    A pointer that doesn't refer to an object should simply be defined as
 335       DataPointer *myDataPointer = 0;
 336
 337 * Basic types:
 338  - Assume T is a given type. When declaring or defining with the
 339    "pointer to T" notation, the * character must be adjacent to
 340    the variable and not the type. That is use
 341       T *foo = 0;
 342    and not
 343       T* foo = 0;
 344    nor
 345       T * foo = 0;
 346  - Assume T is a given type. When declaring or defining with the
 347    "reference to T" notation, the &amp; character must be adjacent to
 348    the variable and not the type. That is use :
 349       T &amp;foo = 0;
 350    and not
 351       T&amp; foo = 0;
 352
 353    (Doxygen will not have any longer to correct)
 354
 355  - Always define a typedef for a new type and be consistent in usage.
 356    Use :
 357       typedef Header *HeaderPointer;
 358       HeaderPointer myHeaderPointer;
 359
 360  - One notorious counter example for non using C style inclusion concerns
 361    exact-width integers (since there seem to be no equivalent for C++).
 362    When using exact-width integers use the typedef names defined by
 363    the Basic ISO C99: 7.18 Integer types i.e.
 364       int8_t     int16_t     int32_t     int64_t (signed integers)
 365    and
 366       uint8_t    uint16_t    uint32_t    uint64_t (unsigned integers).
 367    Conversion table is then:
 368     unsigned char       -&gt; uint8_t;
 369     unsigned short      -&gt; uint16_t;
 370     unsigned int        -&gt; uint32_t;
 371     unsigned long       -&gt; uint32_t;
 372     unsigned long long  -&gt; uint64_t;
 373     (signed) char       -&gt; int8_t;
 374     short               -&gt; int16_t;
 375     int                 -&gt; int32_t;
 376     long                -&gt; int32_t;
 377     long long           -&gt; int64_t;
 378    Hence do not use declarations like "unsigned int".
 379    With g++, accessing those typedef is achieved by the following
 380       #include &lt; stdint.h &gt;
 381 </iostream.h></iostream></pre>
 382
 383
 384 <!--#######################################################################-->
 385 <hr size="1"><address style=""></address>
 386
 387 </body></html>