hpGEM

Coding style of the kernel

Eclipse Users

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

Coding Guidelines

1. General Recommendations
   1. Any violation to the guide is allowed if it enhances readability.
   2. Most conventions are based on the coding guidelines from http://geosoft.no/development/cppstyle.html
2. Naming Conventions
   1. File names must be of the form "FileName".
   2. Directory names must be of the form "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.
   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 of the form "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. Plural form should be used on names representing a collection of objects.
   12. A variable with a large scope should have a long name.
   13. Choose variable names that suggest the usage.
   14. The prefix "numberOf" should be used for variables representing a number of objects.
   15. The suffix "Id" should be used for variables representing an entity number.
   16. The prefix "is" or "do" or "use" or conjugations thereof should be used for boolean variables and methods.
   17. 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 ".cpp".
   3. Application files should have the extension ".cpp".
   4. Implementation files of templated classes should have the extension "_Impl.h" and be included at the end of the 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. A 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.
   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. BASE_ELEMENT_HPP)
   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.
   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. The only exception is upcasting, which may be done implicitly or explicitly.
   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; except for the primitive data types e.g. int.
   8. Use of global variables should be minimized.
   9. Class variables should never be declared public.
   10. C++ pointers and references should have their reference symbol next to the name rather than to the type, i.e. Element *element.
   11. Implicit test for 0 should not be used other than for boolean variables.
   12. Variables should be declared in the smallest scope possible.
   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 initialized 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.
   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 std::size_t for non-negative integer variables.
   24. Encapsulate global variables and constants, enumerated types, and type definitions in a class or namespace.
   25. The "auto"-keyword for type declaration is only allowed if it is instantly clear what the type is.
   26. When using a template, use typename T and NOT class T.
   27. Avoid using "typename" as a return specifier.
   28. 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.
   29. 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 (note 2 spaces before the keywords):

      // space before and after ':' as seen below
      class SomeClass : public BaseClass 
      {
      public: // not indented 
          statements;
      protected: // not indented
          statements;
      private: // not indented
          statements;
      }
      			

   3. Method definitions should have the following form:

      // no space between someMethod and ()
      void someMethod()
      {
          statements;
      }
      			

   4. A for statement should have the following form:

      // space between for and ()
      for (initialization; condition; update)
      {
          statements;
      }
      			

   5. A while statement should have the following form:

      // space between while and ()
      while (condition)
      {
          statements;
      }
      			

   6. The if-else class of statements should have the following form:

      // space between if and ()
      if (condition)
      {
          statements;
      }
      else
      {
          statements;
      }
      			

   7. A switch statement should have the following form:

      switch (condition)
      {
        case ABC :
          statements;
          // Fallthrough
        case DEF :
          statements;
          break;
        default :
          statements;
          break;
      }
      			

   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 may be put in the left column immediately above the function name.

      void
      MyClass::myMethod()
      {
          statements;
      }
      			

   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.
   13. Use // or /// for all comments, including multi-line comments.