FlexSEA Wiki

A WEARABLE ROBOTICS TOOLKIT

User Tools

Site Tools


styleguide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
styleguide [2019/09/11 19:07]
jfduval
styleguide [2019/11/07 20:47] (current)
jfduval
Line 1: Line 1:
 ====== Dephy C/C++ Programming Style Guide ====== ====== Dephy C/C++ Programming Style Guide ======
  
-__**General:**__+===== General ​===== 
  
   * Use <color #​22b14c>​tabulations</​color>,​ not <color #​ed1c24>​spaces</​color>​. If you have to specify the tab size, use 4.   * Use <color #​22b14c>​tabulations</​color>,​ not <color #​ed1c24>​spaces</​color>​. If you have to specify the tab size, use 4.
   * All files need to end with an empty line.   * All files need to end with an empty line.
-  * Do not use ''/​* */''​ for comments that are on a single line, use <​nowiki>​ // </​nowiki>​ +  * Do not use ''/​* */''​ for comments that are on a single line, use <​nowiki>//</​nowiki>​ 
-  * As a general rule, make sure that your code looks clean and similar to the existing code (when existing code is provided) +  * 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 <​nowiki>//</​nowiki>​ and the text.+  * In your comments, start sentences with capital letters. ​Put a space between the <​nowiki>//</​nowiki>​ and the text.
     * Good: <color #​22b14c><​nowiki>//​That'​s a good comment</​nowiki></​color>​     * Good: <color #​22b14c><​nowiki>//​That'​s a good comment</​nowiki></​color>​
     * Bad: <color #​ed1c24><​nowiki>//​ this isn'​t</​nowiki></​color>​     * Bad: <color #​ed1c24><​nowiki>//​ this isn'​t</​nowiki></​color>​
Line 27: Line 28:
   * When in doubt, add more parentheses than needed. It usually makes the code easier to read, and it removes doubts about operator priority.   * 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:**__+===== Functions - Brackets ​=====
  
 <color #​22b14c>​Good:</​color>​ <color #​22b14c>​Good:</​color>​
Line 45: Line 46:
 }</​code>​ }</​code>​
  
-__**Functions - Arguments:**__+===== Functions - Arguments ​=====
  
-Always use the keyword '​void'​ when you do not have an argument.+C ONLY: Always use the keyword '​void'​ when you do not have an argument.
  
 <color #​22b14c>​Good:</​color>​ <color #​22b14c>​Good:</​color>​
Line 57: Line 58:
 <​code>​void my_fct()</​code>​ <​code>​void my_fct()</​code>​
  
-__**Loops and Conditional statements - Brackets:**__+===== 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: Always use brackets, even if you have a single line below the statement. Do not put a space before the parentheses. Example:
Line 77: Line 78:
      ​value3 = 1;</​code>​      ​value3 = 1;</​code>​
  
-__**Conditional statements - Spaces:**__+===== Conditional statements - Spaces ​=====
  
 Do not include a space between if and ().  Do not include a space between if and (). 
Line 89: Line 90:
 <​code>​if (value1 == value2)</​code>​ <​code>​if (value1 == value2)</​code>​
  
-__**Operators and spaces**__+===== Operators and spaces ​=====
  
 <color #​22b14c>​Good:</​color>​ <color #​22b14c>​Good:</​color>​
Line 98: Line 99:
  
 <​code>​myVar = (i*20)/​(a+1)</​code>​ <​code>​myVar = (i*20)/​(a+1)</​code>​
 +
 +===== 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 ====
 +
 +<code 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;​
 +}
 +
 +</​code>​
 +
 +==== thisFile.h ====
 +
 +<code c>
 +//​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
 +</​code>​
styleguide.1568228859.txt.gz · Last modified: 2019/09/11 19:07 by jfduval