SMIL  0.9.1
Contribution Guidelines

Contribution Guidelines

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...

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 :

$ cp -p filename filename.bak
$ clang-format -i -style=file filename

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 :
    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 : 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

  • 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 :
    /**
     * Image Beautifier
     *
     * Image Beautifier based on the algorithm described by John Beautiful
     *
     * @param[in]  imgIn Input image
     * @param[out] imgOut Image beautified
     * /