SCM

Coding Guidelines

From Forge Wiki

Jump to: navigation, search

CamiTK is a big project involving a lot of developers. For its development to go smoothly, do not forget that your changes may impact other developers. Team playing is fun only if plaid by the rules...

Contents

Generic Coding Rules

A must requirement must be followed, a should is a strong recommendation, and a "can" is a general guideline.

  • Tricky code should not be commented but rewritten! In general, the use of comments should be minimized by making the code self-documenting by appropriate name choices and an explicit logical structure
  • CamiTK is an Open Source international project, thus all comments must be in English
  • The use of magic numbers in the code should be avoided. Numbers other than 0 and 1 should be considered declared as named constants instead

Setting Up Your Editor

Indentations must use 4 spaces everywhere, but there must be no indentation for namespaces. Special characters like TAB and page break must be avoided. Here is how to do this

Files organisation

When developping on Linux and MacOS you will have a specific build type (Debug or Release) set for your build directory. Thus, each file compiled on this build will follow this build type. On Windows, using MSVC (Visual Studio compiler) you would have one build for both Debug and Release types. Moreover, each library / application built on a specific type is not compatible with the other one (Debug and Release DLLs are uncompatible at runtime). To counter that, since version 3.1.x of CamiTK, we propose to develop Debug and Release version of the libraries / applications in the same directory. We decided to suffix with an 'd' the debug version of any library and suffixing with '-debug' the name of the application built. Thus, there are no more problem of uncompatible runtime libraries on Windows. This solution has been chosen by Qt (take a look at the bin folder of your Qt install) and is now available for CamiTK delveoppers.

Note that, this switch need to recompile ITK and VTK the same way. See an automatic install script to gain time.


Files and Projects Organization

Each project should be organized as a CamiTK Extension Project (CEP)

Headers and Cpp Files

Header files should be extended by .h and C++ source files should be extended by .cpp.

The name of files should reflect the content of the file as clearly as possible. Files containing class definitions and implementations should contain only one class. The name of the file must be the same as the name of the class. Files may contain more than one class when inner classes or private classes are used.

Other Files

  • CMakeLists.txt
  • README

Headers Files

A particular attention must be paid for header files as they may be included in other files and impact deeply other projects. Here are the guidelines for header files.

Naming Conventions

Directory Names

Directory, package names should be in lower case (with not underscore or space or any type of separators between words), here's why: There are many things to consider (portability, ascendant compatibility, multi-OS support...). CamiTK directory names follows an old Unix idea, that proved later to be safe when using the same tree on Microsoft Windows. It also follows the more modern Object Oriented principle, where a directory is used/can be directly used as a namespace: the directory named is then used for the namespace's name.

It is also on the same wavelength as the Java convention "Package names are written in all lower case to avoid conflict with the names of classes or interfaces", from the Java Documentation (Oracle).

Therefore, CamiTK convention do not allow dash (-), uppercase, space or anytime of separator in the directory names. If it seems to you that the directory name is ugly (e.g., mywonderfulthingyextension), try to be inventive (e.g. try thingy on its own).

File Names

  • Header file names
  • CPP file names
  • Other file names
    • CMakeLists.txt
    • README

Class / Method / Variable Names

For classes, methods and variables, CamiTK use java naming conventions

Open-Source CEPS Developer Specific Rules

The CamiTK Open-Source CEP is quite specific, as it is open to everyone to see. There are specific rules to follow when developing in the Open-Source CEP, they can be found here.

Sources

These pages have been inspired by:

Powered By FusionForge