FlexSEA Wiki

A WEARABLE ROBOTICS TOOLKIT

User Tools

Site Tools


styleguide

Dephy C/C++ Programming Style Guide

Programming in Python? Dephy Python Programming Style Guide.

Looking for a way to review your code? A checklist for this style guide lives here.

General

  • Use tabulations, not spaces. If you have to specify the tab size, use 4.
  • All files need to end with an empty line.
  • Do not use /* */ unless absolutely necessary, such as commenting out large chunks of code. Instead, use //
  • As a general rule, make sure that your code looks clean and similar to the existing code (when existing code is provided). More examples below.
  • In your comments, start sentences with capital letters. Do not put a space between the // and the text.
    • Good: //That's a good comment
    • Bad: // this isn't
  • Always include a comment above a function declaration that explains its purpose.
  • Always mention in what file extern variables are declared.
  • When you use a preprocessor statement such as #ifdef DEF_X, always add a closing comment such as #endif //DEF_X
  • Use the keyword 'ToDo' to flag stuff that should be fixed.
  • Function and variable names should start with a lower case. Use upper case to separate words.
    • Good: int myNewVariable = 0;
    • Bad: int MyNewVariable = 0;
    • Bad: int my_new_variable = 0;
  • All definitions and enumerated types should be in uppercase characters.
    • Good: #define MY_CONSTANT 1
    • Bad: #define myConstant 1
  • On empty lines:
    • Use one to separate different blocks of code
    • Do not use more than one at a time
    • Main objective: code readability
  • When in doubt, add more parentheses than needed. It usually makes the code easier to read, and it removes doubts about operator priority.

Functions - Brackets

Good:

//Description of the function
void myFunction(void)
{
     //My Code
}

Bad:

void myFunction(void){
//My Code
}

Functions - Arguments

C ONLY: Always use the keyword 'void' when you do not have an argument.

Good:

void myFct(void)

Bad:

void myFct()

Loops and Conditional statements - Brackets

Always use brackets, even if you have a single line below the statement. Do not put a space before the parentheses. Example:

Good:

if(value1 == value2)
{
     value3 = 1;
}

Also good:

if(value1 == value2){ value3 = 1; }

Bad:

if(value1 == value2)
     value3 = 1;

Conditional statements - Spaces

Do not include a space between if and ().

Good:

if(value1 == value2)

Bad:

if (value1 == value2)

Conditional compilation

Good:

#ifdef MACRO
     controlled text
#endif //MACRO

Bad:

#ifdef MACRO
controlled text
#endif

Operators and spaces

Good:

myVar = (i * 20) / (a + 1)

Bad:

myVar = (i*20)/(a+1)

File Organization

The idea is not to match the example below to the letter but, to follow the general structure and style. This makes it easier to read various files, move code across them, etc. General guidelines are:

  • Identify what the file does
  • Identify the major sections of your file
  • Use the same section identifier as other files
  • Whenever possible, make function static

thisFile.c

//Description of what this file is about
 
//****************************************************************************
// Include(s)
//****************************************************************************
 
#include "main.h"
#include "thisFile.h"
 
//****************************************************************************
// Variable(s)
//****************************************************************************
 
uint8_t myGlobalVar = 0;
 
//****************************************************************************
// Private Function Prototype(s):
//****************************************************************************
 
static uint8_t computeNewValue(uint8_t dataPoint);
 
//****************************************************************************
// Public Function(s)
//****************************************************************************
 
//This function takes in X to produce Y
uint8_t thisFunction(uint8_t x)
{
	uint8_t i = 0;
	i = computeNewValue(rand());
	return i;
}
 
//****************************************************************************
// Private Function(s):
//****************************************************************************
 
static uint8_t computeNewValue(uint8_t dataPoint)
{
	return dataPoint + FUNCT_INCREMENT;
}

thisFile.h

//Description of what this file is about
 
#ifndef INC_THIS_FILE_H
#define INC_THIS_FILE_H
 
//****************************************************************************
// Include(s)
//****************************************************************************
 
#include "main.h"
 
//****************************************************************************
// Definition(s)
//****************************************************************************
 
#define FUNCT_INCREMENT 5
 
//****************************************************************************
// Shared variable(s)
//****************************************************************************
 
extern uint8_t myGlobalVar;
 
//****************************************************************************
// Public function prototype(s)
//****************************************************************************
 
//This function takes in X to produce Y
uint8_t thisFunction(uint8_t x);
 
#endif //INC_THIS_FILE_H

Doxygen Documentation

Follow this model for oxygen documentation

This needs to be included at the top of a file for the documentation to be generated.

///
/// @file device_wrapper.h
/// FlexSEA API Documentation
/// @author Dephy Inc.

Function documentation in a header file

///
/// \brief Establish a connection with a FlexSEA device.
///
/// \param portName is the name of the serial port to open (e.g. "COM3")
///
/// \param baudRate is the baud rate used i.e. 115200, 230400, etc.
///
/// \param frequency is the frequency of communication with the FlexSEA device.
/// This applies for streaming device data as well as sending commands to the
/// device.
///
/// \param logLevel is the logging level for this device. 0 is most verbose and
/// 6 is the least verbose. Values greater than 6 are floored to 6.
///
/// \returns device ID (-1 if invalid/failed to open), a 16-bit integer used to
/// refer to a specific FlexSEA device
///
/// \note Device ID is used by the functions in this API to specify which FlexSEA
/// device to communicate with. It is used by most of the functions in this library to
/// specify which device to run that function on.
int fxOpen(const char* portName,
		unsigned int baudRate,
		unsigned int logLevel);

Enum documentation

///
/// Motor Control Modes
typedef enum fxControlMode
{
	FxPosition	= 0, /// Position - Send a position setpoint
	FxVoltage	= 1, /// Voltage - Open Control Command
	FxCurrent	= 2, /// Current - Send a current Setpoint command
	FxImpedance	= 3, /// Impedance - Send an impedance command. Position setpoints but with stiffness and damping coefficients
	FxNone		= 4, /// No controller type. Shutoff command.
	FxCustom	= 5,
	FxMeasRes	= 6,
	FxStalk		= 7, /// Send an stalking command. It uses the position controller to stalk an ankle angle at a certain distance
} FxControlMode;

Tools

CLion

In order to fix the code style automatically, please use the CLion Settings Repository. The repository contains setup instructions.

For CLIon usage, see these CLion formatting instructions.

styleguide.txt · Last modified: 2021/04/21 22:07 by casmat