Doc/Website/CodingStyle.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4    <META http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
   5    <TITLE>Gdcm Developpers</TITLE>
   6 </HEAD>
   7
   8 <BODY>
   9
  10 <!#######################################################################>
  11 <H1>Gdcm coding style (and other religious/agnostic beliefs)</H1>
  12 <HR size="1"><ADDRESS style="align: right;"></ADDRESS>
  13
  14 <PRE>
  15 * Introduction:
  16    The following coding style intends to ease the work of developpers
  17    themselves but also of users who will study, maintain, fix, and extend
  18    the code. Any bread crumbs that you can drop in the way of explanatory
  19    names and comments will go a long way towards helping other readers and
  20    developers.
  21    Keep in mind that to a large extent the structure of code directly
  22    expresses its implementation.
  23
  24 * Language:
  25  - C++ (for the kernel) and Python (for the wrappers).
  26  - all the names (variables, members, methods, functions) and comments
  27    should be based on English. Documentation, guides, web site and other
  28    informations should be in English.
  29    Make sure you use correct (basic) English and complete, grammatically
  30    correct sentences for comments and documentation.
  31
  32 * General layout:
  33  - Each line of code should take no more than 79 characters. Break the code
  34    across multiple lines as necessary.
  35  - Methods and functions should keep a reasonable number of lines when
  36    possible (a typical editor displays 50 lines). Avoid code duplication.
  37    Always prefer creating a new method or function to duplication.
  38    A high indentation level generally suggests the need for a new
  39    method or function.
  40  - All the code should be properly indented. The appropriate indentation
  41    level is three spaces for each level of indentation. DO NOT USE TABS.
  42    Set up your editor to insert spaces. Using tabs may look good in your
  43    editor but will wreak havoc in others, or in external tools (e.g. side
  44    by side diffs).
  45  - The declaration of variables within classes, methods, and functions
  46    should be one declaration per line. Provide them with default values
  47    and don't rely on compilers for default initialization.
  48
  49 * Naming conventions:
  50  - Generalities:
  51    In general, names are constructed by using case change to indicate
  52    separate words, as in ImageDataSize (standing for "image data size").
  53    Underscores are not used. Variable names are choosen carefully with the
  54    intention to convey the meaning behind the code. Names are generally
  55    spelled out; use of abbreviations is discouraged.
  56    [Note: abbreviation are allowable when in common use, and should be in
  57     uppercase as in LUT or RGBA.]
  58    While this does result in long names, it self-documents the code.
  59  - Naming Files:
  60    Files should have the same name as the class, with a "gdcm" prepended.
  61    Header files are named .h, while implementation files are named either
  62    .cxx or .txx, depending on whether they are implementations of templated
  63    classes. For example, the class gdcm::Document is declared and defined
  64    in the files gdcmDocument.h and gdcmDocument.cxx.
  65  - Naming Class Data Members, Methods, and Functions:
  66    Class data members are named beginning with a capital letter as in
  67    GroupPixel.
  68    Global functions and class methods, either static or class members, are
  69    named beginning with a capital letter, as in GetImageDataSize().
  70  - Naming Local Variables:
  71    Local variables begin in lowercase. There is more flexibility in the
  72    naming of local variables although they still should convey some
  73    semantics.
  74
  75 * Classes:
  76  - Don't use the inline keyword when defining an inline function
  77    within a class definition.
  78  - As stated in the "Naming conventions" section, class data members
  79    are named beginning with a capital letter as in GroupPixel.
  80    But the parameter names of method should be named with a lowercase
  81    letter (in order to distinguish at a glance data members, from parameters
  82    and also to avoid potential collisions with data members):
  83       void A::SetGroupPixel( int groupPixel )
  84       {
  85          GroupPixel = groupPixel;
  86       }
  87  - Do not repeat the virtual keyword when overriding virtual base methods
  88    in declaration of subclasses:
  89      class A
  90      {
  91         virtual void foo(...);
  92      };
  93      class B: public A
  94      {
  95         void foo(...);          // and not: virtual void foo(...);
  96      };
  97  - The public, protected, private declarations should be at the
  98    same indent level as the class. Use
  99      class A
 100      {
 101      private:
 102         void foo(...);
 103      public:
 104         void bar(...);
 105      };
 106  - Method and functions devoided of arguments should not use the void
 107    notation. Use
 108      SomeType Header::GetPixelData()
 109    and not
 110      SomeType Header::GetPixelData(void).
 111
 112 * Use of braces:
 113  - Braces must be used to delimit the scope of an if, for, while, switch, or
 114    other control structure. Braces are placed on a line by themselves, and
 115    at the same indentation level as the control structure to which they
 116    belong:
 117       for (i=0; * i<3; i++)
 118       {
 119          ...
 120       }
 121    or when using an if:
 122       if ( condition )
 123       {
 124          ...
 125       }
 126       else if ( other condition )
 127       {
 128          ...
 129       }
 130       else
 131       {
 132          ....
 133       }
 134    You can choose to use braces on a line with a code block when
 135    the block consists of a single line:
 136       if ( condition ) { foo=1; }
 137       else if ( condition2 ) { foo=3; }
 138       else { return; }
 139    or
 140       for (i=0; i<3; ++i) {x[i]=0.0;}
 141    Methods and functions should follow the same usage of braces:
 142       void File::ParsePixelData()
 143       {
 144          ...
 145       }
 146
 147 * Special layout:
 148  - Avoid code mixed with comments on a single line. Instead, prepend the
 149    logical blocks of code with the concerned comments.
 150  - Use parentheses around conditions e.g. with an if statement:
 151       if ( someLocalVariable == 2 ) { ... }
 152  - Add spaces around parentheses, or braces. Use
 153       if ( someLocalVariable == 2 ) { ClassMember += 1; }
 154    and not
 155       if (someLocalVariable == 2) {ClassMember += 1;}
 156  - Add spaces around each side of the assignement operator, and
 157    around binary operators used in boolean expression. Use
 158       someLocalVariable = ClassMember * 2;
 159       if ( someLocalVariable == 2 || ClassMember == 2 ) ...
 160    and not
 161       someLocalVariable=ClassMember*2;
 162       if ( someLocalVariable==2||ClassMember==2 ) ...
 163
 164 * Miscelaneous:
 165  - Don't use underscores. Don't use tabs. Don't use control characters
 166    like ^M. Anyhow, cvs is configured to reject such commits.
 167  - Comments should be in C++ style ("// ...", two slashes, per line). Don't
 168    use C style comments ("/* ... */").
 169  - The last line of a file should terminate with "\n".
 170  - Returned arguments of methods and functions should not be wrapped with
 171    parentheses. Use
 172       return iter->second;
 173    but do not use
 174       return ( iter->second );
 175
 176 * Debugging and Verbose modes:
 177    Never use std::cout. Instead use the gdcmDebug class through the
 178    global instance dbg. Example:
 179       #include "gdcmDebug.h"
 180       ...
 181       {
 182          dbg.Verbose(3, "Local function name: entering.");
 183          ...
 184       }
 185     will send the message to std::cout when dbg.Debug() is called
 186     in your main.
 187
 188 * Documentation:
 189    The Doxygen open-source system is used to generate on-line documentation.
 190    Doxygen requires the embedding of simple comments in the code which is in
 191    turn extracted and formatted into documentation. See
 192       http://www.stack.nl/ dimitri/doxygen/
 193    for more information about Doxygen.
 194  - Documenting a class:
 195    Classes should be documented using the class and brief doxygen commands,
 196    followed by the detailed class description:
 197       /**
 198        * \class Header
 199        * \brief Header acts as container of Dicom elements of an image.
 200        *
 201        * Detailed description of the class is provided here
 202        * ...
 203        */
 204    The key here is that the comment starts with /**, each subsequent line has
 205    an aligned *, and the comment block terminates with a */.
 206  - Documenting class members and inline methods:
 207    All the members and the inline methods should be documented within
 208    the class declaration as shown in the following example:
 209       class Header
 210       {
 211          /// True when parsing was succesfull. False otherwise.
 212          bool Readable = false;
 213
 214          /// \brief The number of lines of the image as interpreted from
 215          /// the various elements encountered at header parsing.
 216          int NumberOfLines = -1;
 217
 218          /// Predicate implemented as accessor around \ref Readable.
 219          bool IsReadable() { return Readable; }
 220       };
 221  - Documenting a Method:
 222    Methods should be documented using the following comment block style
 223    as shown in the following example:
 224
 225       /**
 226        * \brief  Within the Dicom Elements (parsed with the public and private
 227        *         dictionaries), look for the element value representation of
 228        *         a given tag.
 229        * @param  group  Group number of the searched tag.
 230        * @param  elem Element number of the searched tag.
 231        * @return Corresponding element value representation when it exists,
 232        *         and the string "gdcm::Unfound" otherwise.
 233        */
 234       std::string Document::GetEntryByNumber(guint16 group, guint16 elem)
 235       {
 236          ...
 237       }
 238
 239 * External includes and C style:
 240  - Only the C++ standard library and the STL includes should be used.
 241    When including don't use the .h extension (use #include <iostream>
 242    instead of #include <iostream.h>).
 243    Note: include the stl header AFTER the gdcm ones (otherwise pragma
 244          warnings won't work).
 245  - Don't use the C standard library. Don't include stdio.h, ctype.h...
 246    Don't use printf(), sprinf(), FILE*...
 247  - Don't use the NULL notation (neither as macro, nor as const int NULL=0).
 248    A pointer that doesn't refer to an object should simply be defined as
 249       DataPointer* MyDataPointer = 0;
 250
 251 * Basic types:
 252  - Assume T is a given type. When declaring or defining with the
 253    "pointer to T" notation, the * character must be adjacent to
 254    the variable and not the type. That is use
 255       T *foo = 0;
 256    and not
 257       T* foo = 0;
 258    nor
 259       T * foo;
 260  - Assume T is a given type. When declaring or defining with the
 261    "reference to T" notation, the & character must be adjacent to
 262    the variable and not the type. That is use :
 263       T &foo = 0;
 264    and not
 265       T& foo = 0;
 266
 267    (Doxygen will not have any longer to correct)
 268
 269  - Always define a typedef for a new type and be consistent in usage.
 270    Use
 271       typedef Header *HeaderPointer;
 272       HeaderPointer MyHeaderPointer;
 273  - One notorious counter example for non using C style inclusion concerns
 274    exact-width integers (since there seem to be no equivalent for C++).
 275    When using exact-width integers use the typedef names defined by
 276    the Basic ISO C99: 7.18 Integer types i.e.
 277       int8_t     int16_t     int32_t     int64_t (signed integers)
 278    and
 279       uint8_t    uint16_t    uint32_t    uint64_t (unsigned integers).
 280    Conversion table is then:
 281     unsigned char       -> uint8_t;
 282     unsigned short      -> uint16_t;
 283     unsigned int        -> uint32_t;
 284     unsigned long       -> uint32_t;
 285     unsigned long long  -> uint64_t;
 286     (signed) char       -> int8_t;
 287     short               -> int16_t;
 288     int                 -> int32_t;
 289     long                -> int32_t;
 290     long long           -> int64_t;
 291    Hence do not use declarations like "unsigned int".
 292    With g++, accessing those typedef is achieved by the following
 293       #include < stdint.h >
 294 </PRE>
 295
 296
 297 <!#######################################################################>
 298 <HR size="1"><ADDRESS style="align: right;"></ADDRESS>
 299
 300 </BODY>
 301 </HTML>