Skip to content

coding style guideline

Fabien Spindler edited this page Sep 20, 2016 · 6 revisions

ViSP coding style guideline

Files

  • Each class has its own header and implementation file
  • A template class has only a header file
  • The file name should match the class name
  • C++ interface headers have .h extension
  • Implementation files have .cpp extension
  • As an example, if the class is named vpMyNewClass, the header file name should be vpMyNewClass.h and the implementation file vpMyNewClass.cpp

File structure

Every source file starts with GPL-v2 license. Use existing code to get the template.

Other rules for both header and implementation files include:

  • Code lines should not be very long. Normally, they should be limited to 100 characters.

  • No tabulation should be used. Set your editor to use spaces instead.

  • Only English text is allowed. Do not put comments or string literals in other languages.

  • Indentation is 2 spaces.

  • Each file (.h or .cpp) should end with an empty line to avoid a compiler warning

  • Each header should include visp3/core/vpConfig.h before other ViSP headers.

  • Header files must use guarding macros, protecting the files from repeated inclusion:

      #ifndef __vpMyNewClass_h_
      #define __vpMyNewClass_h_
    
      #include <visp3/core/vpConfig.h>
      ...
      #endif
    

Naming conventions

  • Class names start with a vp prefix, then each name starts with an uppercase letter. Underscores are not allowed; ie vpMyNewClass
  • Macros and enumeration constants are written with all capital letters. Words are separated by underscore.
  • All external functions and classes must use VISP_EXPORT, otherwise there will be linking errors on Windows.
  • Member or static functions start with a lowercase, then next words with an uppercase; ie vpMyNewClass::myNewMethod().

Class implementation conventions

  • A class should have a default constructor, a virtual destructor and a copy operator. The header file vpMyNewClass.h should contain at least the following:

      class VISP_EXPORT vpMyNewClass
      {
      public:
        vpMyNewClass();                                       // Default constructor
        virtual ~vpMyNewClass();                              // Virtual destructor
        const vpMyNewClass& operator=(const vpMyNewClass &v); // Copy operator
        ...
      };
    

Documentation

The documentation is written in doxygen style. Use the existing documentation as example. Normally, each function/method description includes:

  • a short description
  • all the parameters explained; e.g. specify, which image types are accepted, what would be the recommended values for the parameter and how they affect the algorithm etc.
  • the full description with short use samples, references to papers, formulas, etc

In order to avoid warnings when building with Xcode for iOS, the following style should be adopted for

  • Parameter description: use doxygen \param special command to describe only one parameter:

      /*!
        \param x : Coordinates of a point along x-axis.
        \param y : Coordinates of a point along y-axis.
       */
      void myClass::myMethod(double x, double y)
    

    The following is not allowed:

      /*!
        \param x,y : Coordinates of a point.
       */
      void myClass::myMethod(double x, double y)
    
  • Putting documentation after members: use doxygen ///< special character instead of //!<

      int var; ///< Value used to... 
    

Code layout

Currently used in ViSP and recommended formatting style looks as follows:

  if (B <= A) {
    throw (vpException(vpException::badValue, "Bad gray levels with %d <= %A", B, A)) ;
  }
  unsigned char v;

  double factor = (double)(B_star - A_star)/(double)(B - A);

  for (unsigned int i=0 ; i < I.getHeight(); i++) {
    for (unsigned int j=0 ; j < I.getWidth(); j++) {
      v = I[i][j];

      if (v <= A)
        I[i][j] = A_star;
      else if (v >= B)
        I[i][j] = B_star;
      else
        I[i][j] = (unsigned char)(A_star + factor*(v-A));
    }
  }

The following bracket style is also allowed:

  for (unsigned int i=0 ; i < I.getHeight(); i++)
  {
    for (unsigned int j=0 ; j < I.getWidth(); j++) 
    {
      ...
    }
  }
You can’t perform that action at this time.