StyleGuide

back to home

Style Guide for Developers

The rules for CFS are quite relaxed - only a few items are mandatory to follow. Further guide lines are kind of common sense and might be worth discussing.

Autoformat using clang-format

We recommend to use an auto format for your newly-written code. This can be done using clang-format with the following settings:

{ BasedOnStyle: LLVM, IndentWidth: 2, TabWidth: 2, ColumnLimit: 0, BreakBeforeBraces: Stroustrup}

If you are using VS-Code, you can add the above line to the C_Cpp: Clang_format_fallback Style setting.

NOTE: Please DO NOT use clang-format on whole files, but only on your newly-written code! In VS-Code, you can use ctrl+k+f to format only marked lines of code.

Mandatory rules

• document new code: class descriptions / file header descriptions (if file only contains one class)
• Use no tabs (tabulator) but spaces instead
  • Be aware the the default setting for Eclipse are tabs!
• Use indentation 2
• Use only 7-bit ASCII, check for umlaute as grep --color='auto' -P -n "[\x80-\xFF]" file.xml
• CMake commands must be lowercase, e.g. message(STATUS "hello world") - we are still in progress to convert old cmake code step by step.
• no large scale formatting changes - this will lead to unnecessary merge conflicts

Recommendations to improve code quality

• try to reduce shared_ptr usage: thy are often used but not necessary - use standard pointers instead which will improve performance
• use override for virtual methods

Supported Systems

• we use C++17 (mandatory for CGAL and Ginkgo)
• this implies gcc >= 9
• minimal OpenMP is 2.1 due to the Microsoft compiler - e.g. Ginkgo is compiled with icx to use more recent OpenMP
• supported systems are shown in the README.md

Good Coding Style

Naming conventions

• Class and Function names should start with capital letters
  • class NonLinBlaBla;
  • void CalcDMat();
• The file names should follow the containing class names with the same upper and lower letters
  • NonLinBlaBla.hh and NonLinBlaBla. cc
• Private attributes have a tailing underliner
  • bool valid_;

CMake

• Keep CMake files as simple as possible
• We switch from upper caste to lower case functions ('IF' -> 'if', 'ADD_SUBDIRECTOY()' -> 'add_subdirectory()'. To prevent conflict nightmares we won't automatically change all upper to lower but new code shall be lower case. Variable names are case sensitive and we there keep the upper case style.

Meta-Coding issues

• Try to avoid to much includes in header files, use forward declarations when possible
• Use the Logging feature and do leave out commented cout statements.
• Document your stuff
  • in Doxygen
  • in this Wiki
  • in the XML Reference
• Please, for heaven's sake - don't do copy & paste but extract common functionality to own methods or use object oriented programming techniques!
• Avoid too long functions and classes - this helps to structure the problem.

Hints and Tricks

• Instead of a long if/then/else(if) chain use a switch statement when dealing with a enum.
  • when there is no default statement the compiler prints a warning when the enum gets more values.

Testcases

• use a minimal mat.xml
• use the .h5ref as input
• comment in the description how the generate the mesh input to allow for easy reconstruction with different resolution.