coding style guideline
- 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 bevpMyNewClass.h
and the implementation filevpMyNewClass.cpp
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
- Class names start with a
vp
prefix, then each name starts with an uppercase letter. Underscores are not allowed; ievpMyNewClass
- 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()
.
-
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 ... };
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...
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++)
{
...
}
}