BEST practises

C++/C modules

- Project-wide definitions must be in a dedicated header file (for instance definitions.h)

- Each module may have a common .h file that contains all common constants, macros, enum, structures… It should not contain elements that are not common to classes in the module.

C++/C source files

C++/C source files should contain the implementation of only one class (except for very small private utility classes related to that class). See Naming conventions for naming conventions.

C++/C headers files

C++/C headers files should contain the declaration of only one class (except for very small public utility classes related to that class). See Naming conventions for naming conventions.

Directory layout for each module

The directory layout for each module should be as described in: coding_rules.adoc chapter Project organisation

Templates

Templates should be used following the "KISS" principle. Extreme template programming must be avoided and replaced with ad-hoc design to ensure code maintainability.

Exceptions

Exceptions must not be used outside package boundary (i.e. outside a static or dynamic library no exception must be thrown).

Operator overload

Operator overloading should be used appropriately.

Weird language features of C++

Weird language features of C++ must not be used, especially:

- static variables that invoke constructors at initialization time (except for some very special cases, such as the singleton pattern)

- run-time type information (‘casts’ can fail at run-time)

Bit fields

Bit fields must not be used for the following reasons: they are not portable because the implementation of bit fields is left to the compiler manufacturer according to the platform; and usage of bit fields is usually inefficient in terms of code size. Use one variable instead of each bit field.

Consider using the STL bitset template class instead.

Namespaces

Namespaces may be used for std classes to avoid the full Class::methName statement. But for internal classes with ambiguous names, try to always use their full class name.

'goto' keyword

The 'goto' keyword should not be used, and if it is, it can only be used to jump to the end of a method for error recovery.

By considering the architecture of a method, this keyword can nearly always be avoided. See annex A3 for examples.

‘continue’ and ‘break’ keywords

The ‘continue’ statement should not be used; the ‘break’ statement should not be used except inside switch statements.

‘return’

The 'return' keyword may be used anywhere in the code.

However, it requires that the no dynamic allocation rule is respected (see below) and that no vital code is skipped.

It also requires that all synchronization is made through C++11 lock_guard objects.

C++ types

Types such as bool, etc. may be used if they are not platform dependant.

C++ iostreams

Iostreams should be used.

Dynamic memory allocations

Dynamic memory allocation should be avoided.

Most of the time, C++ offers semantics that allows no dynamic allocation design.

malloc/free, new/delete should be used during initialization sequence (in the class constructors for instance)

During run time, explicit memory allocations should not be used to avoid memory fragmentation and leaks. If an array is needed at some point during the execution of the program, this need should preferably be planned and reserved at the initialization sequence.

Local arrays are recommended if they are small in size (no more than 16-32 values).

Arrays

use STL’s vector<T> and array<T> instead of old C-style arrays, as C-style arrays don’t behave as expected with C++ objects.

Dynamically allocation of member (aggregated/composed) object

dynamic allocation of a "local" object must occur only when the inner object lifetime is different from the "hosting" class (aggregation case) OR when the used framework doesn’t allow the creation of the object upon class creation (for instance, when no default constructor is available).

When dynamically allocating inner objects, prefer the use of STL’s shared_ptr or unique_ptr (depending on the inner object lifetime), to ensure proper behavior upon exception throwing …​

Class instantiations during run time

All the necessary classes, arrays, structures should be present, allocated and initialized before run time (during the initialization sequence) except for transient objects (objects operated by a pipeline should be created at the beginning and destroyed at the end for instance)

Constants

Constants must be declared using static const or enum for enumeration of constants. #define must be avoided (language evolution tends to avoid #statements).

const

const keyword MUST be used. It must be used appropriately.

Used on method parameters, it clearly shows when a parameter is an input, input/output or output parameter.

Used for methods, it clearly shows that const methods leave the underlying object members unmodified. (typically getters should be const methods).

STL containers

STL should be used for container types, such as vectors, lists, maps, etc. (but must not be used across DLL boundaries).

C++ strings

The C++ string object should be used for string manipulation (but must not be used across DLL boundaries).

C++ 'cin', 'cout', 'cerr'

The C++ 'cin', 'cout', 'cerr' must not be used (except inside unit test code and command line tools).

C 'stdin', 'stdout', 'stderr'

The C 'stdin', 'stdout', 'stderr' must not be used (except inside unit test code and command line tools).

C headers/libraries

C headers/libraries may be used.

System specific headers/libraries

System specific headers/libraries must not be used (except in system specific source code – in that case it should be clearly isolated and identified). The code should use as little as possible the windows SDKs (tradeoff between using existing code and code created from scratch).

Multiple header include

To avoid multiple definitions, each header must have:

#ifndef HEADERNAME_H

#define HEADERNAME_H

<header>

#endif // HEADERNAME_H

Include inside header files

#include should not be inside header files in order to avoid include files obfuscation, and to prevent some cases of bad build of a project which shares dependencies with a non-rebuilt project.

Function and variable declaration

Function and variable declarations must be done in header files (and not in other files).

#pragma once

Use of #pragma once is prohibited :

- even if it is supported by a vast majority of c++ compilers, it is not a standard directive of the language

- although it protects from header naming conflict, it doesn’t prevent from ncluding a header twice if it exists in more than one location in a project as files are excluded based on their filesystem-level identity.

About names

- Words must be in English.

- Words inside the name must start with an uppercase letter. Other letters of the word must be lowercase letters (except for constants).

- Names should not contain underscores '_' (except for constants and the prefixes as specified bellow).

- Names should not contain abbreviations (except if the abbreviation is widely used in the particular field, such as ESDescriptor for “elementary stream descriptor”).

- Names should be explicit according to what they will do, avoid generic names (like i, a, x…).

C++ source files

C++ source files must begin with the name of the class followed by ‘.cpp’.

C source files

C source files must begin with the name of the class followed by ‘.c’.

C++/C headers files

C++/C header files must begin with the name of the class followed by ‘.h’.

C++ template headers files

C++ template header files must begin with the name of the class followed by ‘.[inl|tpl]’.

C++ template source files

C++ template source files must begin with the name of the class followed by ‘.[ipp|tcc]’.

Classes, structures, global functions, structure tags, typedefs, enumerated values

Class names, structure names, global functions, structure tags, typedefs, enumerated values must have their name beginning with an uppercase. Example MatrixBase

Methods

Method names must begin with a lowercase letter (except for constructors and destructors). Example readAccessUnit()

Private members

Private member variable names must be prefixed with 'm_' and start with a lowercase letter. Example m_accessUnitList

Private static members

If used, private static member variable names must be prefixed with 's_' and start with a lowercase. Example s_socketCounter

Local variables

Local variable names must start with a lowercase letter. Example dataLength

Constants

Constants must be all uppercase with each word separated by “_”. Example MAX_LENGTH

Multiple inheritance Polymorphism

Multiple inheritances should not be used, except if the additional classes are pure virtual (equivalent to Java interfaces).

Classes with public virtual methods

Classes with public virtual methods must have a virtual destructor (or else the destructor will not be called). When possible, use the appropriate compiler warning to be warn when destructor isn’t declared virtual while some public methods are.

Static member variables

Static member variables must not be used (these are basically “global variables”). (except for singleton design pattern)

Public member variables

Public member variables must not be used (except in pure “struct-like” classes). Instead, getter and/or setter methods should be provided to access member variables. Example int getMember() { …​.return m_member; }

Error setMember(int variable) { …​.if (variable…​) …​.{ …​…​..m_variable = variable; …​…​..return NoErr; …​.} …​.return Error_NUMBER; }

Unsigned/signed types

Signed and unsigned computations should not be mixed. Signed and unsigned doesn’t work well together and are, in many cases, not comparable one another. Situations like “comparing unsigned values with potentially negative values” or “use signed computations to be casted into unsigned variables” makes the code vulnerable.

Signed types

Unsigned types should be used. Signed types should only be used when the value for the variable or parameter in question could sensibly be negative.

'enum' type

For variables or parameters that may take one of a set of values whose representation is arbitrary, the enum type should be used. Example enum CM_Colors { CM_RED, CM_GREEN, CM_BLUE };

Dynamic length structure

It is recommended to avoid structures with dynamic length. However, if they are used, the size should be bounded in size in order to avoid unlimited memory occupation.

Preprocessor definitions

The definition and use of preprocessing flags (#ifdef/#ifndef) in the source code should be limited; in particular, there should not be any OS or compiler specific code. However, if specific code is present, it should be isolated and clearly identified. Most of the time, a different design approach allows to avoid inlined OS preprocessor definitions (namespace or inheritance usage for instance).

Code under conditional compilation flags

Code under #if, #ifdef, #ifndef should be limited. Theses sections, if not build with the rest of the code, can easily be broken without notice.

Inline

Inline may be used instead of macro for functions that are called often and when they are more than one line long.

Range of variables

Consider the range of each variable: each variable should remain local to a code block as much as possible. Variable like the for iterator can remain local to the loop. If the if condition statement block needs a local variable: declare it inside the statement block. This variable will not be visible outside the block, preventing misuse. Note for Intel compilers: before ICC11, declaring a variable into a for statement for (int myVariable;…) resulted in having the variable defined locally to the function containing the for. With ICC11, this variable exists only with the for statement code block. Example if (myCondFct()) { …​. int myLocalVar = methodVar * m_aMember; …​.useMyLocalVar(myLocalVar); } aMethodThatCanNotUseMyLocalVarHere(); myLocalVar is only used in the if statement block. If someone attempts to use it outside, the project will not build. This variable only serves that code block and it is not useful outside. The code is easier to read, no need to monitor myLocalVar, or wonder if it is used elsewhere…

Scope of variables

Avoid using one variable for multiple purposes (the compiler handles this optimization process better than anybody).

Code organization

It is recommended to differentiate: - Functions dedicated to computing. - Functions dedicated to schedule and control the computing functions. - Functions dedicated to data flow management. Example Error computeFunc(UInt32* res, UInt32* sourceTable) { …​.// compute code …​.res = sourceTable[0] * sourceTable[1] + MY_CONST;

Error dataFlowFunc(MyStruct destStruct, MyStruct* sourceStruct) { …​.// copy struct …​.memcpy(destStruct, sourceStruct, sizeof(destStruct));

…​.return NoErr; }

Error controlFunc(MyStruct* destStruct, MyStruct* sourceStruct, UInt32* sourceTable) { …​.Error err; …​.UInt32 res;

…​.err = computeFunc(&res, sourceTable); …​.if (err == NoErr) …​.{ …​…​..err = dataFlowFunc(destStruct, sourceStruct); …​.}

…​.return err; }

Thread concurrency

Use threads with caution. It is recommended to ask architecture experts about the use of threads. Use C++11 threads' library.

Singleton design pattern

This pattern should not be used unless absolutely needed. When used, special care should be taken to consider concurrent access issues; the unique instance should be automatically created in the first call of “getInstance”; and the constructor should be declared as private. Sometimes, a statically created singleton is the prefered choice (more than the dynamically created one).

Casts

Casts should not be used unless absolutely needed. C-style casts must be prohibited and replaced with C++ casts. Example UInt16 var1; UInt32 var2; UInt64 myResult;

myResult = var1 * var2;

myResult = (UInt64) var1 * var2;

myResult = UInt64(var1) * UInt64(var2);

Tabs

Tabs must not be used. Spaces must be used for indentation. Editors should be set to fill with spaces, not tabs. Tab settings tend to be different for editors, printers and web pages. Note: This is obviously an arbitrary choice, but mixing tabs and spaces causes much difficulty in reviewing code…

Indentation

Indentation offset must be set to 4 spaces and is performed according to the following rules: - code surrounded by braces must be indented by one level.

Blank lines

A blank line should be used to separate logically distinct sections of code.

Curly brackets

Compound statements (if, else, else if, while, for, switch, do) must ALWAYS make use of curly brackets, even where the "associated" body only consists of a single line. Structures must use curly brackets around the clause.

Curly brackets

Curly brackets should appear at the beginning of the next line or at the end of the line. Example if (a == b) { …​.c = 0; } else {

}

if (a == b) { …​.c = 0; } else {

}

Parentheses

Although C++ has precedence rules that should ensure a given expression is evaluated in the same order regardless of the compiler, additional parentheses should be used where the order of evaluation is not obvious.

Multiple parentheses

Parentheses on multiple lines must be aligned on the previous parentheses with the same level. Operators must be at the end of the lines. Example if (a == b) && …​..(c == d || …​.(e == f)) if (a == b) && (c == d || …​.(e == f))

Functions

Each function should perform a single well-defined operation. Functions should not be too long. Up to 2 pages of printout or about 100 lines of source code is reasonable. These figures include comments and blank lines.

Source files

Sources files must be small. 1000 lines of source code is reasonable (including comments and blank lines). These files are easier to read and faster to compile (Intel compiler can compile several source files in parallel).

Header files

Header files must be small. 100 lines for headers are reasonable.

Switch

Case/default from a switch statement are written on the same column as the switch keyword. break; and other lines are indented. The break keyword must ALWAYS be on its own line. Mixing the break keyword with processing code makes the code confused : it can be interpreted as "fall-off" code when break is at the end of long lines. Example switch (getStyle(config)) { case STYLE_GOOD: …​.// Ah, it’s so good! …​.break;

case STYLE_BAD: …​.// Oh no, it’s bad! …​.break;

default: …​.// Hmmm! …​.break; }

Instructions

Put one instruction per line.

for

Always put curly brackets in for clause. for instructions must be on their own lines (not on the for line)

Boost::log

Boost::log is the recommended framework to log, as it provides great functionality out of the box without the need for extra/complex configuration

Default error codes and types

The default error codes and error types should be declared in a common b<>com header file.

Type of value returned for error codes

The type of value returned for error codes should be Error. Example Error parseString(char *str);

Memory allocation

A method that attempts to allocate memory must provide an allocation failure mechanism, typically by returning an error code. Note that other methods that call such a method must also provide a failure mechanism, and so on…​ Memory allocation should not be performed in constructors as constructors don’t return error code.

File management

The success of a file opening must be checked and if not successful, the error must be handled appropriately. Files must be closed when no longer used or when an error to exit occurs. When closing the file, the return value must be checked.

Function call

The success of a function call must be checked and if not successful, the error must be handled appropriately. The error codes returned by functions must be tested and treated.

Init/deinit functions

After calling constructors and before destructors, it is sometimes necessary to call init and deinit functions to permit error handling on structures that might fail (as these errors cannot be handled in constructors and destructors.

Compiler warnings

Source code must not have any warnings when compiled on any targeted platform with any targeted compiler (with a reasonably high warning level – at least level 3).

C – C++ interfacing

All C public interfaces (*.h) which may be compiled with a C++ compiler must wrap the contents of the file with the pair of macros BEGIN_EXTERN_C and END_EXTERN_C. Example BEGIN_EXTERN_C

END_EXTERN_C

C++ interfacing

All C class headers (*.h) which may be compiled with a C compiler must include a C API and ensure the non visibility of C code by putting it within an “#ifdef __cplusplus … #endif” statement.

Dynamic library export

The definition of each class or function that is exported in a dynamic library must be preceded by the XX_EXTERN keyword, XX being the prefix for the module to which the class belongs.

Portability

See http://www.mozilla.org/hacking/portable-cpp.html for more miscellaneous recommendations on portability on various platforms. If a rule differs from b<>com coding rules, follow the b<>com coding rule.

Copyright

Each b<>com source and header file must use the template copyright header comment. (See Annex A1: .h) Source from other origins (Open Source for example) may have their own license. In this case, the license must be respected. The headers of third party files must be left intact (then it should not be replaced by b<>com copyright).

Primary documentation of a class

The primary documentation of a class must appear in the header file.

Class description

Each class must have a description before the class declaration. (see Annex A1: class description)

Methods

Each method (public, protected and private) must have a short description before the method declaration. (see Annex A1: setup method description) A method that is already sufficiently documented in the superclass may omit the description or have a single-line comment '// see superclass' (see Annex A1: clone method description)

Member variable

Each member variable must have a description either before the member variable declaration or on the same line. (see Annex A1: member description)

Comments

Comments are written in English. Do not use accented characters in source files. All comments should be “Doxygen” compatible (see Tools). All tags must start with ‘@’ and not ‘\’. Each block of code should be commented. Algorithms must be commented. Bugs from Bugzilla must not be referenced in the code.

/*…/

This type of comment block must be used for comments that apply either to a class, a function, a structure, an enum, a member… which is present below the comment block. (see Annex A1: class description)

//

This comment line should be used inside the code to comment lines in C++ sources. They should be used even for block of comments. (see Annex A2)

/…/

This comment block should not be used for C++ except for the template copyright block on top of the file and for method and variable documentation.

'goto' keyword

The 'goto' keyword must not be used.

‘continue’ and ‘break’ keywords

The ‘continue’ statement must not be used; the ‘break’ statement must not be used outside of switch statements.

C++ → C convertibility

C++ source must always be convertible into C code. If the rules associated with classes are followed, a class can be immediately converted into a structure and a bunch of methods with, as parameter, a handle on the structure that represents the former members.

Recursive code

Recursive code must not be used for performance reasons and lack of control over the code and because no parallelization and optimization are possible.

No class as class member

A class must not contain another class as a member except through pointers.

Structures must not contain arrays

A structure (class or struct) must not contain arrays except through pointers. The size of the structures must remain reasonable.

Dynamic memory allocation

Dynamic memory allocation must not be used. malloc/free, new/delete must be used during initialization sequence (into the class creators for instance) During run time, explicit memory allocation must not be used to avoid memory fragmentation and leaks. If an array is needed at some point during the execution of the program, this need must be planned and reserved at the initialization sequence. Local arrays are tolerated if they are small in size (no more than 16-32 values).

Class instantiations during run time

All the necessary classes, arrays, structures must be present, allocated and initialized before run time (during the initialization sequence).

Dynamic length structure

Dynamic length structures must not be used (in order to avoid unlimited memory occupation).

Uncrustify

Most of the code formatting rules described in this document can be enforced using “uncrustify”.

Doxygen

Doxygen extract comments from the source code and generates documentation. It is recommended to check the comment structure with this tool. Refer to the online manual (http://www.stack.nl/~dimitri/doxygen/index.html) for a complete description of DOxygen rules.