CPP coding guidelines

From NEST

[ Coding_Guidelines ]

Contents 1 Files and names 2 Indentation and whitespace 3 Namespaces 4 Class names 5 Class members 6 Private/"undocumented" class members 7 Inline functions 8 Builtin Types 9 Templates 10 Language Features 11 Language of comments and identifiers 12 Debugging, Quality Control 13 On-Line Reference Documents 14 Compiler 15 Books

Files and names

1. All header files have the extension ".h"
2. All C++ files have the extension "cpp".
3. The use of "cc" is deprecated and is only left for compatibility.
4. Do not use macros to define literal constants. Use const or enum instead.
5. All header files are protected by an #ifdef guard, See [1] sec 9.3.3, p 216. Example.

   #ifndef MYHEADER_H
   #define MYHEADER_H
   // the code
   #endif

Indentation and whitespace

Detailed strategy with regards to indentation is still to be developed. Ideally it should be expressed in the form of switches for indent or Artistic Style. This would allow for auto-indenting on commit, which might not be a good idea. However, local pre-commit hooks might turn out to be very helpful nevertheless.

1. Avoid adding new trailing whitespace; TWS is a bad thing (tm)
2. Avoid mixtures of tabs and spaces; use spaces only
3. When touching a file, it's a good idea to strip TWS and fix indentation, however,
4. Avoid committing whitespace changes together with changes in logic
5. When fixing indentation or whitespace problems, always commit these changes separately!
6. When editing a file, try to stick to the local indentation style for it to remain readable

Namespaces

All symbols for the NEST kernel are declared in the namespace nest

Class names

Class names should use one of the following two schemes

1. Capitalised with capitals as word separators: Example: class MyClass
2. Lower case with underscores to separate words Example: class my_class

Class members

Class members should be lower case with underscores to separate words.

Private/"undocumented" class members

Names of private members and undocumented interface functions should end in an underscore.

Example:

class MyClass
{
  int get_i() const;
private:
  int i_;
}

Inline functions

1. Inlined functions should be placed outside the class declaration, using the keyword inline.
2. Inline declarations should follow their class declaration.
3. The keyword "inline" should appear on a separate line.

Example:

class MyClass
{
  int get_i() const;
private:
  int i_;
};

inline
int MyClass::get_i() const
{
  return i;
}
   

Builtin Types

All code for the nest kernel should use the type aliases, defined in nest.h. Thus, use nest::float_t instead of float.

Templates

1. Template class declarations follow the same style as normal class declarations. This applies in particular to inline declarations (see above).
2. The keyword template followed by the list of template parameters appear on a separate line.

Example

template< typename T>
class MyClass: public T
{
 // code
};

Language Features

1. Use only ISO C++ language features.
2. Prefer ISO C++ library functions over their ISO C library equivalents.
3. Prefer ISO C++ library containers (STL).
4. Prefer C++ headers over their C equivalents.
5. Don't use printf and related functions.
6. Use C++ style cast notation (see [1]).
7. Use the const qualifier where appropriate. Use it consistently (see [5], chapter 6)!
8. Use namespaces and exceptions.
9. Try to avoid static class members which need a constructor (non POD).

Language of comments and identifiers

1. All comments should be written in English.
2. All identifiers, class and function names should be in English.

Debugging, Quality Control

Use the assert macro intensively to check program invariants. [9]

On-Line Reference Documents

1. DinkumWare's Standard C++ Library Reference
2. ISO C++ Press Release

Compiler

NEST compiles with any recent version of the GNU C/C++ Compiler gcc.

Books

We have found the following books to be useful.

1. Stroustrup B (1997) The C++ Programming Language, 3rd Edition, Addison-Wesley
2. Meyers S (1997) Effective C++, 2nd Edition, Addison Wesley
3. Meyers S (1996) More Effective C++, Addison Wesley
4. Coplien J O (1992) Advanced C++ programming styles and idioms, Addison-Wesley
5. Eckle B (1995) Thinking in C++, Prentice Hall
6. Plauger P J, Stepanov A, Lee M, and Musser D R (1998) The Standard Template Library, Comming June 1998, Prentice Hall
7. Plauger P J (1995) The (draft) Standard C++ Library, Prentice Hall
8. Musser D R and Saini A (1996) STL Tutorial and Reference Guide, Addison-Wesley
9. Kernighan B and Ritchie D (1988) The C Programming Language, 2nd Edition, Prentice Hall