Coding Conventions

Code

Variable Names:

  • Lower camel case

e.g. varName

Constant Names:

  • Upper snake case

e.g. CONST_NAME

Function Names:

  • Lower snake case

e.g. function_name

Class Names:

  • Upper camel case

e.g. ClassName

Indentation:

  • 4 spaces per level of indentation
  • No tabs

Brackets:

  • Single space before opening brackets
  • Single space after closing brackets if followed by an else
  • No space before opening parentheses in function declarations/definitions
  • Single space before opening parentheses in if statements
void foo_bar(int i) {
    int varName = (i + 2)/2;

    if (true) {

    } else if (false) {

    } else {

    }
}

Arithmetic

  • No spaces around *, /, % and operators with higher precedence than them (e.g. ++, --, ::, !) with the exceptions of c-style casts and the sizeof operator, which should only have a space preceding them.
  • Single space on either side of +, - and operators with lower precedence than them (e.g. <<, ==, ||) with the exception of comma ,, which only has a space following it.
int varName = (i + 2)/2;
int rem = (i + 2)%2;
int i, j;
i = (int)(2.5*2);
bool x = i == 2 || j == 3;
size_t s = sizeof(int);
size_t s = sizeof(x); // avoid using 'sizeof x' as it can lead to ambiguity when followed by a more complicated expression,

File Structure

File Names:

  • Lower snake case for source and header files, with the name of the file matching class the file contains if the file contains a class (but in lower snake case instead of upper camel case)
  • Note CMake uses upper camel case for its files
  • executables and scripts should be lower-case with a dash separating words

e.g. header: file_name.h

e.g. executable: warg-cv

Directory Structure:

|-- computer-vision
    |-- modules
        |-- core
            |-- include
                |-- header.h
            |-- src
                |-- source.cpp
            |-- CMakeLists.txt
    |-- CMakeLists.txt
    |-- main.cpp
         ...

Header File Formatting

  • Header files should include a doxygen @file block identical to the one below (use correct file name)
  • If the file contains a class declaration, it should also include a doxygen @class block with at minimum a @brief description (Brief descriptions are always shown in doxygen, while long descriptions are ommitted in the brief overview of the functions and this will be blank if no @brief is included)
  • All functions in the header file should have a doxygen comment block containing at minimum a @brief description
    • A longer description, if warranted, should include a description of the function's contract (i.e. the guaranteed results of the function) as well as any other information pertinent to anyone calling the function
    • Function parameters should be described with an @param description
    • Function return value should be described with an @returns description
    • If the function may throw an exception, the circumstances of this and the type of exception thrown should be described in the long description of the function
  • All variables and constants in the header file should have a doxygen comment with at minimum a @brief description
/**
 * @file foo.h
 * @author WARG
 *
 * @section LICENSE
 *
 * Copyright (c) 2015-2016, Waterloo Aerial Robotics Group (WARG)
 * All rights reserved.
 *
 * This software is licensed under a modified version of the BSD 3 clause license
 * that should have been included with this software in a file called COPYING.txt
 * Otherwise it is available at:
 * https://raw.githubusercontent.com/UWARG/computer-vision/master/COPYING.txt
 */

#ifndef FOO_H_INCLUDED
#define FOO_H_INCLUDED

#include "bar.h"

/**
 * @class Foo
 *
 * Foo description goes here
 *
 * @brief Brief description goes here
 */

class Foo : public Bar {
public:

    /**
     * Constructor for foo
     *
     * @param baz description of param baz immediately follows variable name
     */
    Foo(int baz);

    /**
     * Getter for baz
     *
     * @returns description of value returned
     */
    int get_baz();

private:
    /**
     * @brief Description of baz
     */
     int baz;

};

#endif // FOO_H_INCLUDED

Source file formatting

  • Source files should include a doxygen @file block identical to the one below (use correct file name)
  • Source files are not required to have doxygen formatting, but it is recommended that you use it if declaring classes/functions/variables etc. inside the source file
/**
 * @file foo.h
 * @author WARG
 *
 * @section LICENSE
 *
 * Copyright (c) 2015-2016, Waterloo Aerial Robotics Group (WARG)
 * All rights reserved.
 *
 * This software is licensed under a modified version of the BSD 3 clause license
 * that should have been included with this software in a file called COPYING.txt
 * Otherwise it is available at:
 * https://raw.githubusercontent.com/UWARG/computer-vision/master/COPYING.txt
 */

#include "bar.h"
#include "foo.h"

Foo::Foo(int baz) : baz(baz) { }

int Foo::get_baz() {
    // note that while documentation is not required in source files
    //     comments are greatly appreciated
    return baz;
}