The OpenCV Coding Style Guide

The source of this document is here.

1. Foreword

The document is a short guide on code style, used in OpenCV. The core libraries (cv, cvaux) are written in C++, so the document concerns only the codes written in C++.

2. Files

All the functionality must be put into one or more .cpp and .hpp files into the appropriate module of OpenCV (https://code.ros.org/svn/opencv/trunk/opencv/modules).

3. File Structure

Every source file, except for the samples, starts with BSD-compatible license, which template can be found in https://code.ros.org/svn/opencv/trunk/opencv/doc/license.txt. The extra/different copyright clauses are possible, as long as the license stays BSD-compatible.

Other rules for both header and implementation files include:

4. Naming conventions

5. Designing functions and class interfaces

It is important to design function interface is a way, consistent with the rest of the library. The elements of function interface include:

Functionality must be well defined and non-redundant. The function should be easy embedded into different processing pipelines that use other OpenCV functions.

Name should basically reflect the function purpose. There are a few common naming patterns in OpenCV:

Return value should be chosen to simplify function usage. Generally, a function that creates/computes a value should return it. It is the good practice to do so for the functions returning scalar values. However, in case of image processing function it would lead to often allocation/deallocation of large memory blocks, so the image processing functions don't create and return result images rather than modify an output image, passed as a parameter (using non-constant reference).

Functions should not use return value for signaling about critical errors, such as null pointers, division by zero, bad argument range, unsupported image format etc. Instead, they should throw an exception, an instance of cv::Exception or its derivative class. On the other hand, it is recommended to use a return value for signalizing about expected run-time situations that can happen in a correctly working system (e.g. tracked object goes beyond the screen etc.)

Argument types are preferably chosen from the already existing set of OpenCV types: Mat for raster images and matrices, vector<Mat> for collection of images, vector<Point>, vector<Point2f>, vector<Point3f>, vector<KeyPoint> for point sets, contours or collections of key points, Scalar for 1- to 4-element numerical tuples (like colors, quaternions etc.) It is not recommended to use plain pointers and counters, because it makes the interface lower-level, meaning more probable typing errors, memory leaks etc. For passing complex objects into functions, methods, please, consider Ptr<> smart pointer template class.

A consistent argument order is important because it becomes easier to remember the order and it helps programmer to avoid errors, connecting with wrong argument order. The usual order is: <input parameters>, <output parameters>, <flags & optional parameters>.

Input parameters usually have const qualifiers. Large objects are normally passed by a constant reference; primitive types and small structures (int, double, Point, Rect) are passed by value.

Optional arguments often simplify function usage. Because C++ allows optional arguments in the end of parameters list only, it also may affect decisions on argument order—the most important flags go first and less important—after.

For example function and class declarations, take a look at https://code.ros.org/svn/opencv/trunk/opencv/modules/core/include/opencv2/core/core.hpp.

6. Code Layout

There is a single strict coding guideline in OpenCV: each single file must use a consistent formatting style.

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

   1     if( a > 5 )
   2     {
   3         int b = a*a;
   4         c = c > b ? c : b + 1;
   5     }
   6     else if( abs(a) < 5 )
   7     {
   8         c--;
   9     }
  10     else
  11     {
  12         printf( "a=%d is far to negative\n", a );
  13     }

Other styles might be also accepted if only the above rule is met. That is, if one changes written by others code, he (she) should use the same coding style.

7. Portability, External Dependencies

Formally, the code must comply with the C++ standard. However, since All the codes must be compliant with the following standards:

One should get rid of compiler-dependent or platform-dependent constructions and system calls, such as:

8. Writing documentation on functions

The documentation for contributed functions is written in ReStructured Text and built using Sphinx tool. To build documentation, you need a full Live Tex or compatible distribution installed (e.g. texlive-full on Ubuntu, MacTex on Mac, MiKTeX on Windows) and Sphinx, which can be installed with easy_install utility (easy_install -U Sphinx).

Use the existing documentation as example. Normally, each function/method description includes:

9. Implementing tests

11. Appendixes

Appendix A. References The document is not a complete style guide. Far more detailed and well-written papers on this topic are listed below:

Appendix B. The brief list of rules

OpenCVWiki: CodingStyleGuide (last edited 2011-10-10 17:23:02 by ColinTracey)