Coding conventions recommended by the Ceylan project

Overview

We listed here the main conventions we adopted regarding developments, in the hope of promoting:

1. coding good practices [see our dedicated section]
2. a well-documented, homogeneous and easily read code

This document currently focuses on general conventions and on C++ specific ones. It will nonetheless include hints for other languages as well, notably the sh shell, Python and Erlang.

In Makefile.am, header files (*.h) and source files (*.cc) should be listed alphabetically (hint: use /bin/ls -1 *.cc for example), each file being on a line of its own thanks to the \ separator, which should be one space after the variable declaration (ex: LOGS_INTERFACES = \), whereas all filenames, except the last, have a final \ at column 50, with no trailing space.

All tests should be named test + library name + subject, for example: testCeylanLogSource

Regularly, autoupdate should be used to have state-of-the-art configure settings:

Before you release a distribution of your project, it is wise to get the latest versions of `config.guess' and `config.sub' from the GNU site(21), since they may be newer than the versions automatically added by libtoolize and automake. Note that automake --add-missing will give you its own version of these two files if `AC_PROG_LIBTOOL' is not used in the project `configure.in', but will give you the versions shipped with libtool if that macro is present! next: when API is stable and there are users, use libtool library versioning http://sources.redhat.com/autobook/autobook/autobook_91.html#SEC91

Make sure that #if is used instead of #ifdef, since setting a symbol to a value or another (typically, -DA_CEYLAN_SYMBOL=1) is more robust than setting a symbol or not (typically, -DA_CEYLAN_SYMBOL). For example, the -Wundef gcc options issues a warning if an undefined identifier is evaluated in an `#if' directive.

The problem arises when using AC_CHECK_HEADERS: either, if the header is found, it defines and set to 1 a variable (ex: #define HAVE_DUP2 1), either, if the header is not found, it does not define anything special (ex: it does do #define HAVE_DUP2 0 for instance).

So, to rely on -Wundef for our own defines, we may test them with #if CEYLAN_DEBUG and enforce setting a value for each of our symbols (they are defined in all cases, ex: #define CEYLAN_DEBUG 0 or #define CEYLAN_DEBUG 1), and test AC_CHECK_HEADERS-ones simply with #ifdef HAVE_DUP2 instead of #if HAVE_DUP2 (otherwise -Wundef would issue warnings or errors about it).

General purpose coding conventions

File layout

Source file are formatted so that they are best viewed with an 80-column wide text editor, with tabulation stops being four space wide.

Nommage des fichiers

Certains utilitaires d'archivage, tels qu'au moins certaines versions de WinZip, ne supportent pas que deux fichiers, situés à deux endroits de l'arborescence, portent le même nom (tous les fichiers sont stockés ensemble dans l'archive, indépendamment des répertoires). De ce fait, des conventions voudraient que, les répertoires ne formant pas toujours des espaces de nommage cloisonnés, les noms de fichiers soient par exemple préfixés par le nom du projet (ex: OSDLVideo.h). On essaie de respecter cette habitude, dans la mesure du possible.

Bonnes pratiques C++

Fichiers

Correspondance entre type de fichier et extension:

Nommage

• la langue à favoriser pour les développements est l'anglais, pour des raisons de concision, et d'usage international, des non-francophones pour être amenés à travailler sur notre code (correction ou enrichissement) ou à l'utiliser.
• nom des méthodes
• pour favoriser la modularité et diminuer les risques de collision de nom, les espaces de nommage (namespaces), anonymes ou non, seront utilisés (déclaration: namespace myNamespace { ... }, utilisation: using namespace MyNamespace ou MyNamespace::MySymbole).
• les noms des données-membres d'une classes seront préfixés par m_ (ex: m_width): préfixés afin de les distinguer des variables qui ne sont pas des variables de classes, et préfixés spécifiquement par m_ et non pas _ afin d'éviter les ambiguïtés quand du code C++ est compilé avec du code C, pour lequel _unSymbole a un sens particulier.

Expressions

iff means if and only if. Used when two logic expressions are equivalent.

General C++

• No method should be named register, since it is a reserved keyword.
• All classes having at least one data member pointing to dynamic parts should redefine irrelevant default copy C++ behaviours, namely:
  1. the copy constructor: MyClass( const Myclass & source ) throw()
  2. the assignment operator: MyClass & operator = ( const MyClass & source ) throw())
  Note that, if the object should not be copied, one just has to declare them both as private, and does not even need to define them.

Of course, a preferably virtual destructor should be defined on these cases, and at least a classic (non-copy) constructor. Never throw an exception from a destructor, doing so is calling for a disaster.

For all classic constructors that can be called with only one argument (be there only one argument, or multiple arguments, with at least all but one having a default value), the explicit keyword should be used. For example, a declaration such as explicit Object( bool trackInstance = true, bool dropIdentifierOnExit = true ) throw( Log::LogException ) should have the explicit keyword, since a clumsy attempt to call a function f( Object a ) with f( this ) ; (which is an error indeed since it should have been * this, this being a pointer) apparently is interpreted by the compiler as: f( Object( static_cast<bool>( this ))): the pointer this, a numerical type, is converted to a boolean so that the copy constructor can be called as if its two arguments were true (trackInstance because of pointer, dropIdentifierOnExit because of default value).

• const qualifiers should be used everywhere where possible.
• In fonction signatures, the throw statement should always be present and exactly filled, whether the function or method might raise and/or propagate an exception or not (in this cas, throw() would be used).
• Wide use of references should be made.
• Unit tests should be written systematically.
• Never use in header files (*.h) using declarations, such as using std::string or, even worse, using namespace <a namespace>, since every code which would include this header would have global names declared, possibily hiding a lack of internal declaration. Consider, as much as possible, using explicit prefixs each time a type name defined in a namespace is used. Therefore, prefer in header files std::string myString to using std::string; [...] string myString.
• if, in an header file, a type name is used only through a pointer or a reference (such as, for the type myType, aFunction( myType & arg) and myType * aVariable), the compiler does only need a declaration for it (such as class myType ;). It is not necessary for it to have this type's definition. Therefore, only declaring this type in the header file (without #include ...) would accelerate compilation, since less files should have to be read and parsed. For big projects, the gain is obvious.
• avoid, in C++, using the struct data type, and prefer using class declarations: a struct is indeed a particular case of a class, thus a full use of class data type with corresponding public, private and protected statements should be more uniform, and clearer for the reader.
• when checking whether a pointer is null or not, one should preferably compare it to 0 (zero) than to NULL or null or anything else.
• Similarly, true and false boolean values should be used directly, not as #defined' TRUE or FALSE
• In an implementation file (*.C), the necessary header files should be listed at the beginning, from the more specific to the least. For example, file X.c should begin with #include "X.h", then #include "Y.h", then #include <climits>, for example. This allows to check immediatly that the corresponding header file (here, X.h), is defined with all its dependencies, and therefore does not rely on any external includes.
• One and only one log system should be used, the Ceylan::Log one, with its log plugs.
• The first letter of a class static member (data or method) should be uppercased: MyObject::MyStaticMethod, not MyObject::myStaticMethod
• Avoid writing tests implying implicit converting a non-bool type to bool (ex: void * myPointer; if ( myPointer ) ... less readable than if ( myPointer == 0 ) ...

Method order

The three main sections should be not split, and should be ordered this way:

1. public
2. protected
3. private

When enumerating the methods of a class, be it for declaration (*.h) or definition (*.cc), the same order should apply, in each of the three previously discussed main sections:

1. constructors
2. virtual destructor
3. non inherited non-static methods
4. inherited methods
5. static methods

For attributes with get/set accessors (ex: getPeriod and setPeriod), the get method should appear before the set one. If a has method is available (ex: hasPeriod), it should figure previously (has/get/set order).

Please react!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, or if you would like to contribute and help us, even a little bit, drop us a line!