--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head>
+ <meta http-equiv="Content-Type"
+ content="text/html;charset=iso-8859-1"><title>bbtk Developpers</title></head>
+
+<body>
+
+<!--#######################################################################-->
+<h1>bbtk coding style (and other religious/agnostic beliefs)</h1>
+<hr size="1"><address style=""></address>
+
+<pre>* Introduction:
+ The following coding style intends to ease the work of developpers
+ themselves but also of users who will study, maintain, fix, and extend
+ the code. Any bread crumbs that you can drop in the way of explanatory
+ names and comments will go a long way towards helping other readers and
+ developers.
+ Keep in mind that to a large extent the structure of code directly
+ expresses its implementation.
+
+* Language:
+ - C++ (for the kernel) and Python (for the wrappers).
+ - all the names (variables, members, methods, functions) and comments
+ should be based on English. Documentation, guides, web site and other
+ informations should be in English.
+ Make sure you use correct (basic) English and complete, grammatically
+ correct sentences for comments and documentation.
+
+* General layout:
+ - Each line of code should take no more than 79 characters. Break the code
+ across multiple lines as necessary.
+ - Methods and functions should keep a reasonable number of lines when
+ possible (a typical editor displays 50 lines). Avoid code duplication.
+ Always prefer creating a new method or function to duplication.
+ A high indentation level generally suggests the need for a new
+ method or function.
+ - All the code should be properly indented. The appropriate indentation
+ level is TWO spaces for each level of indentation. DO NOT USE TABS.
+ Set up your editor to insert spaces. Using tabs may look good in your
+ editor but will wreak havoc in others, or in external tools (e.g. side
+ by side diffs).
+ - The declaration of variables within classes, methods, and functions
+ should be one declaration per line. Provide them with default values
+ and don't rely on compilers for default initialization.
+
+* Naming conventions:
+ - Generalities:
+ In general, names are constructed by using case change to indicate
+ separate words, as in ImageDataSize (standing for "image data size").
+ Underscores are not used. Variable names are choosen carefully with the
+ intention to convey the meaning behind the code. Names are generally
+ spelled out; use of abbreviations is discouraged.
+ [Note: abbreviation are allowable when in common use, and should be in
+ uppercase as in LUT or RGBA.]
+ While this does result in long names, it self-documents the code.
+ - Naming Files:
+ Files should have the same name as the class, with a "bbtk" prepended.
+ Header files are named .h, while implementation files are named either
+ .cxx or .txx, depending on whether they are implementations of templated
+ classes. For example, the class bbtk::BlackBox is declared and defined
+ in the files bbtkBlackBox.h and bbtkBlackBox.cxx.
+ - Naming Class Data Members, Methods, and Functions:
+ Class data members (aka Attributes) are named beginning with a lower case 'm'
+ (m as 'member'!) followed by capital letter as in mGroupPixel, in order not
+ be confused with methods names.
+ Global functions and class methods, either static or class members, are
+ named beginning with a capital letter, as in GetImageDataSize().
+ - Naming Local Variables:
+ Local variables begin in lowercase. There is more flexibility in the
+ naming of local variables although they still should convey some
+ semantics.
+ - Naming function parameters:
+ Function parameters begin in lowercase. There is more flexibility in the
+ naming of function parameters although they still should convey some
+ semantics.
+
+* Classes:
+ - Don't use the inline keyword when defining an inline function
+ within a class definition.
+ (Any method defined within a .h file is ipso facto considered as 'inline'.
+ Dont write useless stuff!)
+ - As stated in the "Naming conventions" section, class data members
+ named beginning with a lower case 'm' followed by capital letter
+ as in mGroupPixel.
+ But the parameter names of method should be named with a lowercase
+ letter (in order to distinguish at a glance data members, from parameters
+ and also to avoid potential collisions with data members):
+ void A::SetGroupPixel( int groupPixel )
+ {
+ mGroupPixel = groupPixel;
+ }
+ - Don't use trailing ';' in inline function definition.
+ use :
+ void A::SetGroupPixel( int groupPixel ){mGroupPixel = groupPixel;}
+ NOT
+ void A::SetGroupPixel( int groupPixel ){mGroupPixel = groupPixel;};
+ - Do not repeat the 'virtual' keyword when overriding virtual base methods
+ in declaration of subclasses:
+ class A
+ {
+ virtual void foo(...);
+ };
+ class B : public bbtk::A
+ {
+ void foo(...); // and NOT: virtual void foo(...);
+ };
+
+ (when the keyword 'virtual' is used at the parent level, it's propagated
+ for all the child classes)
+
+ - In declaration of subclasses, always preprend the class name with 'bbtk::'
+ in order not to confuse Umbrello ( OpenSource UML diagram generator)
+ class A
+ {
+ ...
+ };
+ class B : public bbtk::A // and NOT: class B: public A
+ {
+ ...
+ };
+ - The public, protected, private declarations should be at the
+ same indent level as the class. Use :
+ class A
+ {
+ public:
+ void bar(...);
+ protected:
+ void foo(...);
+ private:
+ void pff(...);
+ };
+
+ - The Data members should be declared at the end of the class declaration :
+ class A
+ {
+ public:
+ void bar(...);
+ protected:
+ void foo(...);
+ private:
+ void pff(...);
+
+ // --- Data members
+
+ public:
+ int mPublicCounter;
+ protected:
+ int mProtectedCounter;
+ private:
+ int mPrivateCounter;
+ };
+
+ - Method and functions devoided of arguments should not use the void
+ notation. Use :
+ SomeType Header::GetPixelData()
+ and not
+ SomeType Header::GetPixelData(void)
+
+* Use of braces:
+ - Braces must be used to delimit the scope of an if, for, while, switch, or
+ other control structure. Braces are placed on a line by themselves, and
+ at the same indentation level as the control structure to which they
+ belong:
+ for (i=0; * i<3; i++)
+ {
+ ...
+ }
+ and NOT :
+ for (i=0; * i<3; i++) {
+ ...
+ }
+ or when using an if:
+ if ( condition )
+ {
+ ...
+ }
+ else if ( other condition )
+ {
+ ...
+ }
+ else
+ {
+ ....
+ }
+ and NOT :
+ if ( condition ) {
+ ...
+ } else if ( other condition ) {
+ ...
+ } else {
+ ....
+ }
+ You can choose to use braces on a line with a code block when
+ the block consists of a single line:
+ if ( condition ) { foo=1; }
+ else if ( condition2 ) { foo=3; }
+ else { return; }
+ or
+ for (i=0; i<3; ++i) {x[i]=0.0;}
+ Methods and functions should follow the same usage of braces:
+ void File::ParsePixelData()
+ {
+ ...
+ }
+
+* Special layout:
+ - Avoid code mixed with comments on a single line. Instead, prepend the
+ logical blocks of code with the concerned comments.
+ - Use parentheses around conditions e.g. with an if statement:
+ if ( someLocalVariable == 2 ) { ... }
+ - Add spaces around parentheses, or braces. Use
+ if ( someLocalVariable == 2 ) { mClassMember += 1; }
+ and not
+ if (someLocalVariable == 2) {mClassMember += 1;}
+ - Add spaces around each side of the assignement operator, and
+ around binary operators used in boolean expression. Use
+ someLocalVariable = mClassMember * 2;
+ if ( someLocalVariable == 2 || mClassMember == 2 ) ...
+ and not
+ someLocalVariable=mClassMember*2;
+ if ( someLocalVariable==2||mClassMember==2 ) ...
+
+* Miscelaneous:
+ - Don't use underscores. Don't use tabs. Don't use control characters
+ like ^M. Anyhow, cvs is configured to reject such commits.
+ - Comments should be in C++ style ("// ...", two slashes, per line). Don't
+ use C style comments ("/* ... */").
+ - The last line of a file should terminate with "\n".
+ - Returned arguments of methods and functions should not be wrapped with
+ parentheses. Use
+ return iter->second;
+ but do not use
+ return ( iter->second );
+
+* Debugging and Verbose modes:
+ Never use std::cout. Instead use the bbtkMessage, bbtkDebugMessage, bbtkWarning or bbtkError macros and their variants. Example:
+ #include "bbtkMessageManager.h"
+ ...
+ {
+ bbtkDebugMessageInc("MyClass",9,"Local function name: entering.");
+ ...
+ bbtkDecTab("MyClass",9);
+ }
+ will send the message to std::cout when the Debug messages are compiled
+ and the Message Level for the category of messages "MyClass" is greater than 9.
+
+* Documentation:
+ The Doxygen open-source system is used to generate on-line documentation.
+ Doxygen requires the embedding of simple comments in the code which is in
+ turn extracted and formatted into documentation. See :
+ http://www.stack.nl/~dimitri/doxygen/
+ for more information about Doxygen.
+ - Documenting a class:
+ Classes should be documented using the class and brief doxygen commands,
+ followed by the detailed class description:
+ /**
+ * \class Header
+ * \brief Header acts as container of Dicom elements of an image.
+ *
+ * Detailed description of the class is provided here
+ * ...
+ */
+ The key here is that the comment starts with /**, each subsequent line has
+ an aligned *, and the comment block terminates with a */.
+ - Documenting class members and inline methods:
+ All the members and the inline methods should be documented within
+ the class declaration ( .h file) as shown in the following example:
+ class Header
+ {
+ /// True when parsing was successfull. False otherwise.
+ bool mReadable = false;
+
+ /// \brief The number of lines of the image as interpreted from
+ /// the various elements encountered at header parsing.
+ int mNumberOfLines = -1;
+
+ /// Predicate implemented as accessor around \ref mReadable.
+ bool IsReadable() { return mReadable; }
+ };
+ - Documenting a Method:
+ Methods should be documented using the following comment block style
+ as shown in the following example:
+
+ /**
+ * \brief Within the Dicom Elements (parsed with the public and private
+ * dictionaries), look for the element value representation of
+ * a given tag.
+ * @param group Group number of the searched tag.
+ * @param elem Element number of the searched tag.
+ * @return Corresponding element value representation when it exists,
+ * and the string "bbtk::Unfound" otherwise.
+ */
+ std::string Document::GetEntryByNumber(guint16 group, guint16 elem)
+ {
+ ...
+ }
+
+* External includes and C style:
+ - Only the C++ standard library and the STL includes should be used.
+ When including don't use the .h extension (use #include <iostream>
+ instead of #include <iostream.h>).
+ Note: include the stl header AFTER the bbtk ones (otherwise pragma
+ warnings won't work).
+ - Don't use the C standard library. Don't include stdio.h, ctype.h...
+ Don't use printf(), sprinf(), FILE*...
+ - Don't use the NULL notation (neither as macro, nor as const int NULL=0).
+ A pointer that doesn't refer to an object should simply be defined as
+ DataPointer *myDataPointer = 0;
+
+* Basic types:
+ - Assume T is a given type. When declaring or defining with the
+ "pointer to T" notation, the * character must be adjacent to
+ the variable and not the type. That is use
+ T *foo = 0;
+ and not
+ T* foo = 0;
+ nor
+ T * foo = 0;
+ - Assume T is a given type. When declaring or defining with the
+ "reference to T" notation, the & character must be adjacent to
+ the variable and not the type. That is use :
+ T &foo = 0;
+ and not
+ T& foo = 0;
+
+ (Doxygen will not have any longer to correct)
+
+ - Always define a typedef for a new type and be consistent in usage.
+ Use :
+ typedef Header *HeaderPointer;
+ HeaderPointer myHeaderPointer;
+
+ - One notorious counter example for non using C style inclusion concerns
+ exact-width integers (since there seem to be no equivalent for C++).
+ When using exact-width integers use the typedef names defined by
+ the Basic ISO C99: 7.18 Integer types i.e.
+ int8_t int16_t int32_t int64_t (signed integers)
+ and
+ uint8_t uint16_t uint32_t uint64_t (unsigned integers).
+ Conversion table is then:
+ unsigned char -> uint8_t;
+ unsigned short -> uint16_t;
+ unsigned int -> uint32_t;
+ unsigned long -> uint32_t;
+ unsigned long long -> uint64_t;
+ (signed) char -> int8_t;
+ short -> int16_t;
+ int -> int32_t;
+ long -> int32_t;
+ long long -> int64_t;
+ Hence do not use declarations like "unsigned int".
+ With g++, accessing those typedef is achieved by the following
+ #include < stdint.h >
+</iostream.h></iostream></pre>
+
+
+<!--#######################################################################-->
+<hr size="1"><address style=""></address>
+
+</body></html>
git://git.creatis.insa-lyon.fr / bbtk.git / blobdiff