2 # ---------------------------------------------------------------------
4 # Copyright (c) CREATIS (Centre de Recherche en Acquisition et Traitement de l'Image
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
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.
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
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 # ------------------------------------------------------------------------ */
28 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
30 <meta http-equiv="Content-Type"
31 content="text/html;charset=iso-8859-1"><title>bbtk Developpers</title></head>
35 <!--#######################################################################-->
36 <h1>bbtk coding style (and other religious/agnostic beliefs)</h1>
37 <hr size="1"><address style=""></address>
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
45 Keep in mind that to a large extent the structure of code directly
46 expresses its implementation.
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.
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
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
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.
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.
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
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
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
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 )
117 mGroupPixel = groupPixel;
119 - Don't use trailing ';' in inline function definition.
121 void A::SetGroupPixel( int groupPixel ){mGroupPixel = groupPixel;}
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:
128 virtual void foo(...);
130 class B : public bbtk::A
132 void foo(...); // and NOT: virtual void foo(...);
135 (when the keyword 'virtual' is used at the parent level, it's propagated
136 for all the child classes)
138 - In declaration of subclasses, always preprend the class name with 'bbtk::'
139 in order not to confuse Umbrello ( OpenSource UML diagram generator)
144 class B : public bbtk::A // and NOT: class B: public A
148 - The public, protected, private declarations should be at the
149 same indent level as the class. Use :
160 - The Data members should be declared at the end of the class declaration :
175 int mProtectedCounter;
180 - Method and functions devoided of arguments should not use the void
182 SomeType Header::GetPixelData()
184 SomeType Header::GetPixelData(void)
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
191 for (i=0; * i<3; i++)
196 for (i=0; * i<3; i++) {
204 else if ( other condition )
215 } else if ( other condition ) {
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; }
226 for (i=0; i<3; ++i) {x[i]=0.0;}
227 Methods and functions should follow the same usage of braces:
228 void File::ParsePixelData()
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; }
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 ) ...
247 someLocalVariable=mClassMember*2;
248 if ( someLocalVariable==2||mClassMember==2 ) ...
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
258 return iter->second;
260 return ( iter->second );
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"
267 bbtkDebugMessageInc("MyClass",9,"Local function name: entering.");
269 bbtkDecTab("MyClass",9);
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.
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:
285 * \brief Header acts as container of Dicom elements of an image.
287 * Detailed description of the class is provided here
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:
297 /// True when parsing was successfull. False otherwise.
298 bool mReadable = false;
300 /// \brief The number of lines of the image as interpreted from
301 /// the various elements encountered at header parsing.
302 int mNumberOfLines = -1;
304 /// Predicate implemented as accessor around \ref mReadable.
305 bool IsReadable() { return mReadable; }
307 - Documenting a Method:
308 Methods should be documented using the following comment block style
309 as shown in the following example:
312 * \brief Within the Dicom Elements (parsed with the public and private
313 * dictionaries), look for the element value representation of
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.
320 std::string Document::GetEntryByNumber(guint16 group, guint16 elem)
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;
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
346 - Assume T is a given type. When declaring or defining with the
347 "reference to T" notation, the & character must be adjacent to
348 the variable and not the type. That is use :
353 (Doxygen will not have any longer to correct)
355 - Always define a typedef for a new type and be consistent in usage.
357 typedef Header *HeaderPointer;
358 HeaderPointer myHeaderPointer;
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)
366 uint8_t uint16_t uint32_t uint64_t (unsigned integers).
367 Conversion table is then:
368 unsigned char -> uint8_t;
369 unsigned short -> uint16_t;
370 unsigned int -> uint32_t;
371 unsigned long -> uint32_t;
372 unsigned long long -> uint64_t;
373 (signed) char -> int8_t;
377 long long -> int64_t;
378 Hence do not use declarations like "unsigned int".
379 With g++, accessing those typedef is achieved by the following
380 #include < stdint.h >
381 </iostream.h></iostream></pre>
384 <!--#######################################################################-->
385 <hr size="1"><address style=""></address>