Back to developer page.

C++ coding conventions and style guide

We try to maintain a consistent coding style because it makes reading and modifying the code easier. Our coding conventions aren't necessarily better than others (though we try to follow ones that make sense and change those that don't), but the main utility of this is consistency.

We're much stricter these days than we were, say, 10 years ago. The reason for this is that a codebase with many contributors and large size is much harder to maintain than a small one. So new code must pass tougher tests than some of the existing code. (Of course, the existing code should ideally be cleaned up more, too, but few people are motivated to work on such tasks if there are other things to do that seem more urgent.) Once code is in, it usually isn't changed for years unless we discover a bug. So we really try to put a lot of effort on making things as right as possible on the first try.

The following is not meant to be a complete description of our coding conventions. When in doubt, follow the example of the existing code.

See also the information on how and where to put ../Whitespace.

General recommendations

We generally follow the recommendations in the book C++ Coding Standards: 101 Rules, Guidelines, and Best Practices by Herb Sutter and Andrei Alexandrescu. In the tracker or elsewhere, a mark of the form [SA x] is a reference to a rule in that book. For example, [SA 9] refers to Sutter and Alexandrescu's rule 9: "Don’t pessimize prematurely".

Comments

   1 // Write complete sentences ending with periods.
   2 
   3 // Use imperative if possible: "Return the factorial." is better than "Returns the factorial.".
   4 
   5 // Leave a space between the slashes and the comment.
   6 
   7 /*
   8   Use this style for comments
   9   spanning over multiple
  10   lines and keep in mind that
  11   "the best kind of comments are the ones you don't need"
  12   (http://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/).
  13 */

Namespaces

• Every subdirectory should correspond to a namespace.
• Avoid nested namespaces or subdirectories of subdirectories.

• Namespaces follow the same camel-case naming convention as classes, while directory names follow the naming conventions for methods and variables. For example, file my_subdir/my_class.h would be expected to contain a definition of class MySubdir::MyClass.

• Namespaces should have short, single-word names if possible. (The previous example only uses an underscore in the subdirectory name for sake of illustration.)

Header file guards

Macro names for header file guards follow this algorithm:

• Take the filename, including subdirectory name if in a subdirectory.
• Convert to uppercase.

• Replace all "." and "/" with "_".

Example: learning/state_space_sample.h becomes LEARNING_STATE_SPACE_SAMPLE_H.

Guard blocks should look like this:

   1 #ifndef LEARNING_STATE_SPACE_SAMPLE_H
   2 #define LEARNING_STATE_SPACE_SAMPLE_H
   3 // ...
   4 #endif
   5 

That's all. In particular, don't add comments to the preprocessor directives and don't add further underscores.

Function signatures

• Use const methods whenever appropriate.

• Pass strings by const reference.

• When overriding a virtual method, mention virtual again in the declaration (i.e., virtual int foo(); rather than int foo();).

Anti-idioms

• Don't write NULL for null pointers. Write 0. (The latter is slightly preferred in C++, unlike C. C++ 0x will change that, but we're not there yet. In any case, it's not good to mix styles.)

• Don't write (ptr != 0). Write (ptr).

• Don't write (ptr == 0). Write (!ptr).

• Don't write (seq.size() == 0). Write (seq.empty()).

• Don't write (seq.size() != 0). Write (!seq.empty()).