Table of Contents
This is about good programming practices : what to do and not in your programs. Suggestions about reliability, security, …
Writing programming guidelines specific to a project is a long, tedious and and useless task while there are very good references on the subject.
Take the time, even slowly, to read and understand some references…
- Programming :
- C++ Core Guidelines by Bjarne Stroustrup and Herb Sutter;
- Style Guides :
- Reliability :
Some common mistakes or bad practices :
- warnings are acceptable just while still debugging. Code in the master branch shall be free of warnings (same as errors);
- code doing different things, even if related, shall be break down in different source files (modular programming);
- avoid duplication of source code;
- as in french language, words/symbols/tokens/operators shall be separated by spaces (clang-format may solve this…);
- meaningless (or wrong meaning) variable names;
- hard coding (using something like “# define SIZE 256”) for parameters which can change with time or limit the usability of the program;
- lack of out of bounds checking;
- adequate error and exception handling;
- forgetting to remove “dead code” (some lines useful only while the code was being debugged/validated);
- incoherence over time : not doing the same thing the same way at different moments.
Code formatting isn't just an aesthetic issue. An homogeneous and clear presentation contributes to unambigous and easy understanding.
The code style is that proposed by LLVM with some small enhancements. And the tool is clang-format.
Formatting is done simply with the following commands, the first one just creates a backup copy before formatting, inplace, the original source code :
$ cp -p filename filename.bak $ clang-format -i -style=file filename
- no problem if you don't follow this style. It's enough to run the formatter on the final version of your file, before integrating it to the master or develop branch;
- the choosen style has minors differences from LLVM style. These differences are set at .clang-format file placed at the root of source file tree :
AllowShortFunctionsOnASingleLine: false BreakBeforeBraces: Linux AlignConsecutiveAssignments: true AlignConsecutiveDeclarations: true NamespaceIndentation: All ReflowComents: true SortIncludes: false SortUsingDeclarations: false
clang-format packaged as :
- Ubuntu : clang-format
- CentOS/RedHat/Fedora : clang
clang-format documentation can be found here
Source file prototypes
To help you start with your coding, inside directory
dev-tools, you'll find two files :
As you can see at file
DProto.hpp, the content inside headers file shall be protected by a couple
“#ifdef _SOMETHING_H” and “#endif” directives, to avoid a code being included twice.
The way to build these variable is defined from the filename :
- a “_” (underline) is used as a prefix;
- “.” (dot) are converted to “_”;
- words are separated by “_” even it they don't appear this way in the filename.
As an example, if the filename is
DMorphoBestCode.h, the directive name becomes
To be done !!!
- Avoid meaningless names. Exceptions may be for some usual loop control variables : x, y, z, i, j, k;
- Files :
- C++ source filenames begin always with D;
- File extensions per directory :
- src : .cpp - C++ source files
- include : .h - C++ headers
- include/private : .hpp - C++ headers
- Functions and Methods
- Macros and defines : every character in uppercase.
Source code documentation with Doxygen
To be done !!!
Doxygen / clang-format Oddities
To be verified !!!
- Use “
@tag” syntax instead of “
clang-formatdoesn't handle these two constructions the same way and, sometimes, may break the structure. It seems that using “
@tag” gives more predictable results. Still better, remember : be coherent and do the same thing the same way all the time.
- for the same reason, always insert a blank comment line between two blocks of
doxygendocumentation. For example, between description and parameters of some function :
/** * Image Beautifier * * Image Beautifier based on the algorithm described by John Beautiful * * @param[in] imgIn Input image * @param[out] imgOut Image beautified * /