RSS Feed

Coding style of the kernel

    Eclipse Users

    For eclipse users you can import the coding guidelines from the file found here.

    The guidelines

  1. General Recommendations
    1. Any violation to the guide is allowed if it enhances readability or if it significantly improves the speed of the code.
    2. Most conventions are based on the coding guidelines from
  2. Naming Conventions
    1. File names must be in mixed case starting with upper case, i.e. "FileName".
    2. Directory names must be in mixed case starting with upper case, i.e. "DirectoryName".
    3. Names representing types must be in mixed case starting with upper case, i.e. "TypeName".
    4. Variable names must be in mixed case starting with lower case, i.e. "variableName".
    5. Named constants (including enumeration values) must be all uppercase using underscore to separate words, i.e. MY_CONSTANT.
    6. Names representing methods or functions must be verbs and written in mixed case starting with lower case, i.e. "functionName".
    7. Names representing Classes must be in mixed case starting with upper case, i.e. "ClassName".
    8. Names representing template types should be a single uppercase letter.
    9. Private class variables should have "_" suffix.
    10. Never use identifiers which begin with one or two underscores (`_' or `__'). In most cases those variables are used in imported libraries.
    11. Choose clear variable names that suggest the usage (e.g. BaseParticle* p, Mdouble interactionRadius).
    12. Plural form should be used on names representing a collection of objects.
    13. The prefix "n" should be used for variables representing a number of objects.
    14. The suffix "Id" should be used for variables representing an entity number.
    15. The prefix "is", "has" (for nouns) or "do" (for verbs) should be used for boolean variables and methods.
    16. Negated boolean variable names must be avoided.
  3. Files
    1. C++ header files should have the extension ".h".
    2. Source files should have the extension ".cc".
    3. Driver files should have the extension ".cpp".
    4. Implementation files of templated classes should have the extension ".hcc" and be included at the end of the regular header file.
    5. Large source files can be split in multiple files by using the same name, then an "_" and a description of its usage.
    6. Whenever possible, class should be declared in a header file and defined in a source file where the name of the files match the name of the class.
    7. All definitions should reside in source files.
    8. Special characters like TAB and page break must be avoided. Most editors have the option to expand tabs into spaces, so that the TAB key can still be used.
    9. Header files must contain an include guard. The name convention resembles the location of the file inside the source tree. (all capitals i.e. WALL_STRAIGHTWALL_H)
    10. Include statements must be located at the top of a file only; except, for template class implementations.
  4. Statements
    1. The parts of a class must be sorted public, protected and private, however typedefs must be on the top of the file.
    2. Within the parts methods should go before variables.
    3. Use the "explicit" keyword for single argument constructors.
    4. Type conversions must always be done explicitly, never rely on implicit type conversion.
    5. For every "new", there must be a "delete" in the same class. If the "delete" is in another class, it must be documented carefully with both the "new" and "delete".
    6. Variables must never have dual meaning.
    7. Multiple variables should not be declared on the same line.
    8. Use of global variables should be minimized.
    9. Class variables should never be declared public.
    10. Variables should be declared in the smallest scope possible.
    11. C++ pointers and references should have their reference symbol next to the type rather than to the name. (i.e. BaseParticle* p)
    12. Implicit test for 'false' should not be used other than for boolean variables, e.g. 'if(isFixed)' when isFixed is a boolean, but 'if (p == nullptr)' if p is a pointer.
    13. Only loop control statements must be included in the for() construction.
    14. Range based for-loops are preferred over other types of for-loops. For example, a for-loop over vector vec can look like for ( double& d: vec) { }.
    15. Loop variables should be initialised immediately before the loop.
    16. Do-while loops can be avoided.
    17. The use of break and continue in loops should be avoided, go for readability. In these cases, a small function with a return is usually more readable.
    18. The form while (true) should be used for infinite loops.
    19. In cases of an if-statement, the nominal case should be put in the if-part and the exception in the else-part.
    20. Floating point constants should always be written with decimal point and at least one decimal. (i.e. x = 0.0).
    21. Use nullptr instead of NULL or 0.
    22. Try to avoid smart pointers. If a smart pointer is necessary, use unique_ptr or shared_ptr.
    23. Use the type unsigned int for non-negative integer variables.
    24. The "auto"-keyword for type declaration is only allowed if it is instantly clear what the type is.
    25. When using a template, use typename T and NOT class T.
    26. Avoid using "typename" as a return specifier.
    27. Try to avoid "typedef" for type definitions. Use the "using"-keyword if either the type is likely to change, or the typename is very long. This should be done in the class declaration and not globally.
    28. Avoid returning by final function argument (for example void myFun (int a, int b, Matrix& mat) for computing mat).
  5. Layout
    1. Basic indentation should be 4 spaces. Empty lines should be indented.
    2. Class declarations should have the following form:
      // space before and after ':' as seen below
      class SomeClass : public BaseClass 
      public: // not indented 
      protected: // not indented
      private: // not indented
    3. Method definitions should have the following form:
      // no space between someMethod and ()
      void someMethod()
    4. A for statement should have the following form:
      // space between for and ()
      for (initialization; condition; update)
    5. A while statement should have the following form:
      // space between while and ()
      while (condition)
    6. The if-else class of statements should have the following form:
      // space between if and ()
      if (condition)
    7. A switch statement should have the following form:
      switch (condition)
        case ABC :
          // Fallthrough
        case DEF :
        default :
    8. Single statement if-else, for or while statements can be written without brackets, but have to be on two lines.
    9. The function return type can be put in the left column immediately above the function name.
    10. White spaces
      1. Conventional operators should be surrounded by a space character.
      2. C++ reserved words should be followed by a white space.
      3. Commas, semicolons and colons should be followed by a white space.
      4. Semicolons in for statements should be followed by a space character.
    11. Variables in declarations can be left aligned.
    12. Use alignment wherever it enhances readability.
  6. DoxyGen
    1. All DoxyGen style comments must have the following form:
       * Comments.
       * More comments.
    2. For every class, there must be both brief (\brief) and detailed (\details) DoxyGen style documentation in the header file (.h).
       * \brief This is a class.
       * \details This is a class that is used as an example on the MercuryDPM website
    3. For every member function, there must be brief (\brief) DoxyGen style documentation in the header file (.h). The detailed (\details) DoxyGen style documentation must go into the implementation file (.cc/.hcc).
    4. For every member function with input parameters, the parameters must be documented like

       * \param[in] name Description of the parameter.
      void myFunction(int name)
      { ... }
    5. For every member function with a return value, the return value must be documented like

       * \return Description of the return value.
      int myFunction()
      { ... }
    6. If you find a bug, please mark it with \bug and a description of the bug in DoxyGen style. If you think something has to be done in the future at that piece of code, document it in DoxyGen style with \todo in front.