tacam-cpp-guidelines.md

TACAM Cpp Guidelines

Sections

• General
• Formatting
• Naming
• Comments
• Glossary
• VSCode

General

• Be consistent across the entire project! Do this even if the project being worked on does not follow these guidelines. Consistencies is more important than correctness.

Formatting

Separate Source and Header Files

If the IDE supports separated .cpp and .h, whether that be with virtual folder and real ones. Separate .h files in to the "include" folder and .cpp files into "src" folder.

Example

|-- include
|   |-- Main.h
|-- src
|   |-- Main.cpp 

Includes

When using #include, use " " for files that are part of the source project and < > for library files.

Example

#include <Arduino> // good
#include "main.h" // good
#include "stdio.h" // bad

Curly Brackets

Place opening curl brackets on a separate line.

Example

void function() // good
{
	/* code */
}

void function() { // bad
	/* code */
}

Single Line Conditional Statements

Avoid using single line conditional statements (if, for, while). Uses of condition statements without curly brackets are okay but should be used sparingly and only if nothing else will every need to be added.

Example

if (condition) state = 1; // bad
if (condition) // okay
	state = 1;
if (condition) // good
{
	state = 1;
}

Single Line Functions

Single line functions are okay but should only be used for getters and setters.

Example

int getValue() { return value; } // okay

Naming

Variables and Functions

Variables and functions should be written in Camel Case and be as descriptive as possible.

Example

int getNumber();
int buttonUp;

Classes, Struct and Enums

Classes, structures and enumerations should be nouns and be written in Pascal Case.

Example

class LedCube;
struct Point;
enum State;

Macros

Macros (defines) should be written in all caps separated with underscores this includes members of an enum.

Example

#define DEBUG 1
#define DEBUG_PRINT(x) Serial.print(x)
enum State
{
	ON,
	OFF,
	IDLE,
};

File Names

File names should be written in Snake Case

Example

main.h
main.cpp
time_lib.h

Avoid Abbreviations

Abbreviation may be clear to one person but unclear to another. Try to avoid using abbreviations as much as possible. Only use abbreviations when the meaning is extremely clear but even then consider writing the name in full instead.

Example

class fmt; // bad - format is only 3 more letters..
class format; // good
int next; // good
int prev; // okay - very clear when used with "next"

Avoid "Magic Numbers"

Numbers should be given a name or a useful comment explaining their purpose.

Example

int area = 3.14 * pow(3); // bad
int areaOfCircle = PI * pow(radius) // good

Avoid Types in Variable Names

Your IDE will tell you the type of the variable, adding the type only adds unneeded clutter.

Example

class PersonClass // bad
{
	String nameString; // bad
	int ageInt; // bad
};
PersonClass *personPointer; // bad

class Person // good
{
	String name; // good
	int age; // good
};
Person *person; // good

Comments

General Comments

Comments are very important and should be used frequently. They should be used to explain why or how code works instead of the what the code does.

Example, good

// This define must be placed before #include "ESP32_New_TimerInterrupt.h"
#define _TIMERINTERRUPT_LOGLEVEL_ 0 // _TIMERINTERRUPT_LOGLEVEL_ from 0 to 4
#include "ESP32TimerInterrupt.h"

Example, bad

int area = width * height; // area equals width times the height

Function Comments

Use brief, param, return to document public functions. These comments should be placed in the .cpp file unless the function is define only in the .h file.

Example

/**
 * \brief Adds 10 to a number
 * \param A number to be added
 * \return The number plus 10
 */
int addTen(int number) { return number + 10; }

Glossary

PascalCase

Pascal case is when the first letter every word in a variable is capitalized.

int PascalCase;

CamelCase

Camel case is when other than the first letter every word in a variable is capitalized.

int camelCase;

SnakeCase

Snake case is when words in variable are separated by a under score.

int snake_case;