Coding Guidelines for Developers

Those guidelines are intended for developers who contribute to eblearn, to provide coherent, easy to read and bug-free code.

Documentation

  • Comment your code as much as possible so users can understand it.
  • Use the commenting syntax that can be used to automatically generate the online documentation (with Doxygen):
  • If you edit some code that is missing documentation, add it.

General Architecture

  • The general user interfaces (GUI) have been kept separated from the core code to keep it clean and simple and to allow users to use only the core functionalities when necessary. Thus, try to maintain that separation between essential code and non-essential code (e.g. guis are separate in libidxgui and libeblearngui and helping tools in libeblearntools).

SVN

  • Never commit a broken code in the main trunk (allowed in branches).
  • Run the tester before a commit to make sure nothing is broken.
  • To work temporarly on code that may not work immediately, create a svn branch in the branches directory. This way you can commit broken code without affecting the main trunk. Once your code works, merge your branch into the trunk.

Debugging

  • Emacs and GDB form a very convenient debugger: execute debug.sh to open Emacs in a debugging setting. In the top left window, use 'file my_exe' to load your executable, 'r my_arguments' to run it, 'break my_main.cpp:42' to break at line 42 in main.cpp (or click on the line the left-hand side). After a crash or a break, click on the stack lines in the bottom-left window to see the position in the code for each layer of the stack. You can also recompile by pressing F12.
  • Once in a while, use valgrind to track memory leaks: e.g. valgrind ./tester

Testing

  • When writing a new module or new code, add some unit tests in the tester (eblearn/tester) that test the basic functionalities of the code, to ease the detection of new bugs.
  • Regularly run the tester when adding code.

Coding Style

  • 80 columns max (Emacs' default), easier for 80-column developers.
  • No unnecessary empty lines between code (user can see more code vertically).
  • Naming convention: no capital letters, use _ instead (C++ style).
  • Open braces on the same line as function prototype (Java style).
  • Indent code (use "c++"->"indent region" in Emacs).
  • Try to keep functions small.
  • Avoid code redundancy, instead write sub functions.
  • File directories and extensions:
    • include/*.h: prototypes of classes, funtions, etc.
    • include/*.hpp: template implementations.
    • src/*.cpp: implementations.