]> Creatis software - gdcm.git/blob - Doc/Website/CodingStyle.html
* Bug fix for python use
[gdcm.git] / 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 = 0;
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>