X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?a=blobdiff_plain;f=Doc%2FWebsite%2FCodingStyle.html;h=1b0eb06fad83f94b7a94e6027161cd811e7fd997;hb=9f28ad122dd01f096e4e5ca18d46aa7a8a0a07fc;hp=d62d019ff0f71a74aad4f01dcfc0ca514157c161;hpb=2231ee3a3a73117305f6dcbe90acf0b4aed24b3e;p=gdcm.git diff --git a/Doc/Website/CodingStyle.html b/Doc/Website/CodingStyle.html index d62d019f..1b0eb06f 100644 --- a/Doc/Website/CodingStyle.html +++ b/Doc/Website/CodingStyle.html @@ -48,9 +48,9 @@ * Naming conventions: - Generalities: - In general, names are constructued by using case change to indicate + 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 chosen carefully with the + 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 @@ -71,7 +71,11 @@ 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. @@ -84,6 +88,11 @@ { GroupPixel = groupPixel; } + - Don't use trailing ';' in inline function definition. + use : + void A::SetGroupPixel( int groupPixel ){GroupPixel = groupPixel;} + NOT + void A::SetGroupPixel( int groupPixel ){GroupPixel = groupPixel;}; - Do not repeat the virtual keyword when overriding virtual base methods in declaration of subclasses: class A @@ -147,12 +156,12 @@ * Special layout: - Avoid code mixed with comments on a single line. Instead, prepend the logical blocks of code with the concerned comments. - - Use parantheses around conditions e.g. with an if statement: + - Use parentheses around conditions e.g. with an if statement: if ( someLocalVariable == 2 ) { ... } - - Add spaces around parantheses, or braces. Use - if ( someLocalVariable == 2 ) { ClassMenber += 1; } + - Add spaces around parentheses, or braces. Use + if ( someLocalVariable == 2 ) { ClassMember += 1; } and not - if (someLocalVariable == 2) {ClassMenber += 1;} + if (someLocalVariable == 2) {ClassMember += 1;} - Add spaces around each side of the assignement operator, and around binary operators used in boolean expression. Use someLocalVariable = ClassMember * 2; @@ -168,7 +177,7 @@ 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 - parantheses. Use + parentheses. Use return iter->second; but do not use return ( iter->second ); @@ -189,7 +198,7 @@ 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/ + 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, @@ -212,7 +221,7 @@ bool Readable = false; /// \brief The number of lines of the image as interpreted from - /// the various elements encountered at header parsing. + /// the various elements encountered at header parsing. int NumberOfLines = -1; /// Predicate implemented as accessor around \ref Readable. @@ -226,12 +235,12 @@ * \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 element Element number of the searched 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 "gdcm::Unfound" otherwise. */ - std::string Document::GetEntryByNumber(guint16 group, guint16 element) + std::string Document::GetEntryByNumber(guint16 group, guint16 elem) { ... } @@ -244,20 +253,31 @@ 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 (either as macro, or as const int NULL=0). + - 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 type and not the variable. That is use + 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; + 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; + 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++). @@ -279,7 +299,7 @@ long long -> int64_t; Hence do not use declarations like "unsigned int". With g++, accessing those typedef is achieved by the following - #include + #include < stdint.h >