On this page, we describe best coding practices for SG++.
We have both Boost unit tests (in C++) and Python unit tests. The tests can be found in the test subdirectory of each module. New tests should be written preferably with Boost. However, there is some extra functionality in Python which can be tested only in Python, of course.
If you modify existing code, do not forget to make sure that no new errors are introduced. If you write new functionalities, do always add unit tests for each functionality!
The documentation has to be Doxygen compatible. Doxygen tags must be used in the Java-style way, i.e., starting with
During development tags like
@todo should be used wherever applicable. They are then listed on the Todo page.
Different source files can be grouped together in so-called modules. The link to the page listing all modules can be found in the navigation bar of the documentation. Note that this page and the page listing all examples are autogenerated when running SCons.
Please correct any warnings or errors that appear when creating the documentation with Doxygen!
doxygen in the main folder creates the Doxygen documentation in the subfolder
doc. The settings for Doxygen are taken from
Doxyfile. This file is automatically created based on
Doxyfile_template each time
scons is exectued, therefore, for modifications, please change
The complete code has to be commented elaborately. The comments, together with the identifiers, have to enable others to familiarize with the code quickly. Header files have to be commented completely. In source files, it suffices to comment the codelines. The comments have to be verbose enough so that one can understand what is going on without reading the code! Please use Doxygen-compatible comments for classes and methods.
Compliance with the style guide is important to write good code. A style guide is more than a bunch of indentation rules; rather, it is the art of creating easily reusable, understandable, and refactorable code.
We adhere mostly to the Google C++ Style Guide. However, there are some exceptions:
To ensure compliance with most rules of the style guide, Google's Python script cpplint.py is used (in a slightly modified version located in tools/cpplint.py). By default, on every invokation of SCons, it is automatically run on each *.cpp or *.hpp file which was modified since the last run of SCons. If issues are found, warnings of the following form are printed on the screen:
base/src/sgpp/globaldef.hpp:95: warning: Namespace should be terminated with "// namespace sgpp" [readability/namespace] 
The number in brackets at the end indicates the confidence that the line is indeed a problem, using a scale from 1 to 5 (5 means certainness). Be aware that some warnings are filtered out deliberately to implement the exceptions above.
Currently, SCons generates empty *.lint files whose modification times are used to track which files have to be analyzed. Delete the lint files to retrigger the analysis of all code files:
find base/src/ -name '*.cpp.lint' -or -name '*.hpp.lint' | xargs rm
You can deactivate the style checking (and thus the creation of the *.lint files) by setting
RUN_CPPLINT=0 on the SCons command line.
You can also use a formatter tool to automatically format your code which should fix most of the "easy" style warnings (indentation, line length, etc.). We recommend using clang-format, which can be installed on an Ubuntu system using
apt-get install clang-format-3.7
You can format all files in-place with a command like the following:
find base/src/ -name '*.hpp' -or -name '*.cpp' | xargs clang-format-3.7 -style=file -i
The configuration of the formatter is done via the file
.clang-format at top level.
If you are developing with Eclipse, clang-format and cpplint can also be applied automatically on every file save by using a slightly modified version of the Eclipse plugin CppStyle, which is also included in the tools directory of SG++ (the modification was necessary since CppStyle does not analyze hpp files). To install the plugin, simply copy the *.jar to the dropins subdirectory in your Eclipse installation location (i.e., not your workspace directory). The configuration is then done by clicking on Window → Preferences → C/C++ → CppStyle. Enter the paths to the clang-format executable (e.g., in /usr/bin) and to the cpplint.py script (tools/cpplint.py). Finally, check Enable cpplint and Run clang-format on file save.
sgpp_MODULENAME.hpp. Only include the header files you require to avoid long building durations.
include "Foo.hpp"); use angle brackets instead (
include <../Foo.hpp>). Always use absolute paths (