Coding Standards

This year, we are attempting to have a cleaner code base, so we are experimenting with coding standards. These standards should be considered both during development and during the pull request review process. These guidelines are not rigid, but it should help to create more readable code.

Python

For python code, please adhere to the best practices advocated by the Python Software Foundation. This can be found at their website (python.org).

C and C++

These guidelines are currently a rough draft open to modification. Please submit feedback to Parker.

General

• Code should be broken into separate files representing different modules or sub-modules
• Each .c/.cpp file should have an accompanying .h file along with a valid makefile
• Nested sections of code should be indented with 4 spaces (most editors can use a soft tab of 4 spaces).
• Blocks of code should be separated with an extra newline to visually break up the code.
• Any code which is not intuitive should have a comment describing its action.
• Code should include a README if there are any special instructions for compiling or running (e.g. requires specific libraries)
• In general, stick with using either // or /* */ commenting throughout your program for uniformity rather than mixing and matching both. (Parker's Note: I use /* */ comments, but I use // comments for TODOs. This way, I can search for the // string and fix all of my TODOs, and the final code is left with just /* */ style comments.)
• Avoid "Magic Numbers" -- basically do not hard code values into anything. If you have constant numbers, make them a const or #DEFINE with some descriptive name. For example, pin numbers should be in #DEFINE statements rather than directly inserted into the code.

Standard Header

Every source and header file should contain a standard header with the file name and a brief description. The original file author's name may optionally be included.

Example

/*****************************************************************************
 * UTK IEEE Robotics 2015-2016
 * File: block_setup.cpp
 * Author: Parker Mitchell
 *
 * Description: Implements a basic block position randomization program
 * which allows for different course setups for each run.
 ****************************************************************************/

The standard header should span 79 columns wide. The template provided above may be copied and pasted for use.

Variable names

Variable names should be descriptive except in the case of temporary and iterating variables. Multiple words should be delimited by the use of an underscore '_', and the entire variable name should consist of lower case alphanumeric characters and underscores.

Example

char block_color; /* two lower case words delimited by an underscore */
int i; /* use of i is ok if being used as a loop counter, etc. */

Functions

Code should be broken into readable and reusable functions isolated to performing a specific task. Each function should be accompanied by a small comment block which offers a description of what the function is. Additionally, if it is not immediately clear how to use the function, a brief description of how to use it should be embedded.

Every function should have a matching prototype provided in the appropriate header file. Functions which are intended to be used only within that specific file may be declared to be static.

Example

/*----------------------------------------------------------------------------
 Reads image data from a file into the raw data with dimensions
----------------------------------------------------------------------------*/
void read_img( string filename, Magick::Blob &blob, int &width, int &height )