Differences

This shows you the differences between two versions of the page.

Link to this comparison view

doc:contribute:style [2019/02/22 12:37] (current)
Line 1: Line 1:
 +
 +
 +====== Programming Style ======
 +
 +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** :
 +    * [[https://​isocpp.github.io/​CppCoreGuidelines/​CppCoreGuidelines|C++ Core Guidelines]] by Bjarne Stroustrup and Herb Sutter;
 +  * **Style Guides** :
 +    * [[https://​llvm.org/​docs/​CodingStandards.html|LLVM Coding Style]]
 +    * [[https://​google.github.io/​styleguide/​|Google Style Guides]]
 +  * **Reliability** :
 +    * [[http://​www.codingstandard.com/​|PRQA - High Integrity C++ Coding Standard Version 4.0]]
 +
 +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 ======
 +
 +
 +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 :
 +
 +<code bash>
 +$ cp -p filename filename.bak
 +$ clang-format -i -style=file filename
 +</​code>​
 +
 +<​note>​
 +Obs :
 +
 +  * 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 :
 +</​note>​
 +
 +<​code>​
 +    AllowShortFunctionsOnASingleLine:​ false
 +    BreakBeforeBraces: ​               Linux
 +    AlignConsecutiveAssignments: ​     true
 +    AlignConsecutiveDeclarations: ​    true
 +    NamespaceIndentation: ​            All
 +    ReflowComents: ​                   true
 +    SortIncludes: ​                    false
 +    SortUsingDeclarations: ​           false
 +</​code>​
 +
 +''​clang-format''​ packaged as :
 +  * Ubuntu : clang-format
 +  *CentOS/​RedHat/​Fedora : clang
 +
 +''​clang-format''​ documentation can be found [[https://​clang.llvm.org/​docs/​ClangFormat.html|here]]
 +
 +
 +====== Source file prototypes ======
 +
 +To help you start with your coding, inside directory ''​dev-tools'',​ you'll find two files : ''​dev-tools/​DProto.hpp''​ and ''​dev-tools/​DProto.cpp''​.
 +
 +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 ''​_D_MORPHO_BEST_CODE_H''​.
 +
 +====== Naming guidelines ======
 +''​
 +**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
 +  * Classes
 +  * Variables
 +  * 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 "''​\tag''"​ : ''​clang-format''​ doesn'​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 ''​doxygen''​ documentation. For example, between description and parameters of some function :
 +
 +<​code>​
 +    /**
 +     * Image Beautifier
 +     *
 +     * Image Beautifier based on the algorithm described by John Beautiful
 +     *
 +     * @param[in] ​ imgIn Input image
 +     * @param[out] imgOut Image beautified
 +     * /
 +</​code>​
 +
 +
  
doc/contribute/style.txt ยท Last modified: 2019/02/22 12:37 (external edit)
CC Attribution-Share Alike 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0