Skip to content

Raven Code Style

Jump to bottom
quinnabrvau edited this page Apr 30, 2018 · 1 revision

Much of the Raven code was developed before determining a style guide and therefore many older files are not congruent with the guidlines specified in this repository. Updating the old files may be the subject of future work, but for now we advise all new files follow the conventions detailed here.

Two files in this repo exist for ensuring code compliance with common Raven style conventions:

  • .clang_format -- configuration file used by Clang to clean up whitespace errors

  • cpplint_raven.py -- python script to detect code style errors

When naming objects, names should identify what a function, class, or variable does in as simple a way as possible. Only abbreviate words in cases where it is very obvious (e.x. amp for Ampere). Other naming conventions:

  • functions should be named using lowerCamelCase ( e.x. void someFunctionForFun (void) )

  • file names should be lower case without spaces (use _ for separating words (e.x. grav_comp.cpp))

  • variables currently don't have a standard naming convention.

Clang Setup (linux)

Install clang_format:

$ sudo apt-get install -y clang-format-3.6

Then symlink or copy in the root of your project directory the file .clang_format, located in this repo. For example, place it on your computer here:

/opt/raven_2/raven_ros/raven_2/.clang_format

Now any file inside your project directory will be formatted with the Raven whitespace conventions.

Note: clang makes changes to your files and while it is highly unlikely these changes will affect code execution behavior, this cannot be guaranteed

Clang Usage

Open your preferred terminal.

Format single file:

clang-format-3.6 -i -style=file file.cpp

or to output changed file and compare with a diff tool:

clang-format-3.6 -style=file file.cpp > file_clanged.cpp

Format entire directory recursively including subfolders:

find . -name '*.h' -or -name '*.hpp' -or -name '*.cpp' | xargs clang-format-3.6 -i -style=file $1

For more information on Clang, please refer to the Clang documentation.

Cpplint Setup

Copy the file cpplint_raven.py, located in this repo to the root of your project directory. For example, place it on your computer here:

/opt/raven_2/raven_ros/raven_2/cpplint_raven.py

Cpplint Usage

Open your preferred terminal.

Run on a single file:

python cpplint_raven.py file.cpp 2> file_linted.txt

Run on entire directory recursively including subfolders:

python cpplint_raven.py $( find . -name \*.h -or -name \*.cpp | grep -vE "^\.\/build\/" ) 2> cpplint_results.txt

Output a error categorical summary of a project:

python cpplint_raven.py --counting=detailed $( find . -name \*.h -or -name \*.cpp | grep -vE "^\.\/build\/" ) 2>&1 | grep -e "Category" -e "Total error"

The style guide and cpplint_raven.py are based on those developed by Google. For more information on the lint tool, see message below.

This is automated checker to make sure a C++ file follows Google's C++ style guide (https://google.github.io/styleguide/cppguide.html). As it heavily relies on regular expressions, cpplint.py won't catch all violations of the style guide and will very occasionally report a false positive. There is a list of things we currently don't handle very well at the top of cpplint.py, and we welcome patches to improve it.

The linting tool takes a list of files as input. For full usage instructions, please see the output of:

./cpplint_raven.py --help

Comments

File header blocks

All files should have two block comments at the top.

The first should define the copyright, license and warranty rules that apply to all files. Copy this from existing up-to-date .cpp files.

The second should define the file. It should include sections in the comment which contain the following tags:

  • \file - file name
  • \brief - a one line description of the file
  • \desc - a longer description of the file and potentially any algorithms that were used
  • \fn - list of functions and where they are referenced in the file
  • \log - a log of when changes were made and by whom
  • \author - a list of people who have edited the file, sorted by date of persons first change
  • \data - date the file was created
  • \ingroup - what group is this file a part of (should generally be part of control in master)

These tags are used by Doxygen for automatic generation of documentation.

Example

/** \file  grav_comp.cpp
 *
 *  \brief Functions for calculating gravity torques
 *
 *  \desc  These functions will calculate gravity loads on each of the first 3 DOFs with predefined mass properties.
 *         However, arbitrary gravity vectors can be specified in the currParams data structure, which are then
 *         used in these calculations.
 *
 *  \fn    These are the 3 functions in grav_comp.cpp file. 
 *         Functions marked with "*" are called explicitly from other files.
 *             (1) getCurrentG
 *        *(2) getGravityTorque         :uses (1)(3)
 *             (3) getMotorTorqueFromJointTorque
 * 
 *  \log   Re-written March 2013 by Andy Lewis and Hawkeye King
 *         Equations re-derived for UW Kinematics formulations for Raven II
 *         See Andy's MS thesis or ICRA '14 paper for technical details.
 * 
 *  \author Hawkeye King
 *          Andrew Lewis
 *
 *  \date February 2013
 *
 *  \ingroup control
 */

Functions

Doxygen tags are also needed in an initial multi-line comment inside each function:

  • The first line should define the function name
  • \brief - defines what the function does
  • \param - one line for each parameter and what the value means in english
  • \return - one line for each parameter returned and what the value means in english (should include values returned from a return statement or a change to a variable passed by reference)

Example

/**
* getCurrentG()
* \brief Return the current gravity vector from whatever power knows it
*
* \param device   the robot device that needs gravity compensation
* \param m        the current mechanism (arm) being compensated
*
* \return gravity vector in m/s^2
*/
Clone this wiki locally