Coding Style Rules

The benefits of coding standards are readability, maintainability and compatibility. Any member of the development team in Sming should be able to read the code of another developer. The developer who maintains a piece of code tomorrow may not be the coder who programmed it today.

Therefore we enforce coding standards described in our Style Guide. The coding style rules are mandatory for the Sming/SmingCore and samples directories and all their sub-directories. And they should be applied to all C, C++ and header files in those directories.

A Pull Request that does not adhere to the coding style rules will not be merged until those rules are applied.

Tools

Tools will help you easily adhere to the coding standards described in our Style Guide without the need to know them by heart.

Installation

Clang-Format and Clang-Tidy

In order to automatically check and apply our coding standards you need to install clang-format and optionally clang-tidy.

In Ubuntu you should be able to install them using the following command

sudo apt-get install clang-format clang-tidy

See the the download page of the Clang project for installation instructions for other operating systems.

We are using version 5.0 of clang-format and clang-tidy on our Continuous Integration (CI) System. If possible try to install the same version or newer on your development computer.

Configuration

Rules

The coding rules are described in the .clang-format which can be found in the root directory of the project. You don't have to change anything on this file unless it is discussed and agreed coding style change.

IDE integration

There are multiple existing integrations for IDEs that can be found at the bottom of that page ClangFormat.html.

Eclipse IDE

For our Eclipse IDE, which is our preferred IDE, we recommend installing the CppStyle plugin. You can configure your IDE to auto-format the code on "Save" using the recommended coding style and/or format according to our coding style rules using Ctrl-Shift-F (for formatting of whole file or selection of lines). Read Configure CppStyle for details.

Usage

Command Line

Single File

If you want to directly apply the coding standards from the command line you can run the following command

cd $SMING_HOME
clang-format -style=file -i SmingCore/<modified-file>

Where SmingCore/<modified-file> should be replaced with the path to the file that you have modified.

All files

The following command will run again the coding standards formatter over all C,C++ and header files inside the Sming/SmingCore and samples directory.

cd $SMING_HOME
make cs

The command needs time to finish. So be patient. It will go over all files and will try to fix any coding style issues.

Eclipse

If you have installed CppStyle as described above you can either configure Eclipse to auto-format your files on "Save" or you can manually apply the coding style rules by selecting the source code of a C,C++ or header file or a selection in it and run the Format command (usually Ctrl-Shift-F).

Style Guide

You don't have to know by heart the coding style but it is worth having an idea about our rules. Below are described some of them. Those rules will be can be automatically applied as mentioned in the previous chapter.

Indentation

We use tabs for indentation. Configure your editor to display a tab as long as 4 spaces. Below are the corresponding settings in clang-format.

TabWidth:        4
UseTab:          Always
IndentWidth:     4

Naming

Identifier type	Rules for naming	Examples
Classes	Class names should be nouns in UpperCamelCase, with the first letter of every word capitalised. Use whole words — avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).	class HttpClient {} class HttpClientConnection {}
Methods	Methods should be verbs in lowerCamelCase or a multi-word name that begins with a verb in lowercase; that is, with the first letter lowercase and the first letters of subsequent words in uppercase.	bind(); getStatus();
Variables	Local variables, instance variables, and class variables are also written in lowerCamelCase. Variable names should not start with underscore (_) or dollar sign ($) characters. This is in contrast to other coding conventions that state that underscores should be used to prefix all instance variables. Variable names should be short yet meaningful. The choice of a variable name should be mnemonic — that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.	int i; char c; WebsocketClient* client;
Constants	Constants should be written in uppercase characters separated by underscores. Constant names may also contain digits if appropriate, but not as the first character.	#define MAX_PARTICIPANTS 10;

C++ Standard

For the moment we recommend the use of C++11. The corresponding settings in clang-format are:

Standard:        Cpp11
Cpp11BracedListStyle: true

Starting and ending spaces

We don't recommend the use of a starting or ending space in angles, container literals, c-style cast parentheses, parentheses and square brackets. Our settings are

SpaceAfterCStyleCast: false
SpaceBeforeParens: Never
SpaceInEmptyParentheses: false

SpacesInAngles:  false
SpacesInContainerLiterals: false
SpacesInCStyleCastParentheses: false
SpacesInParentheses: false
SpacesInSquareBrackets: false

See the meaning of those keys and their selected values in the ClangFormatStyleOptions document.

Line length

We are living in the 21st century so most of the monitors should be capable of displaying 120 characters per line. If a line is longer than those characters it will be split whenever possible.

ColumnLimit:     120

Empty Lines

Two or more empty lines will be compacted to one. Also we delete empty lines at the start of a block.

KeepEmptyLinesAtTheStartOfBlocks: false
MaxEmptyLinesToKeep: 1

Braces

BraceWrapping:
    AfterClass:      false
    AfterControlStatement: false
    AfterEnum:       true
    AfterFunction:   true
    AfterObjCDeclaration: false
    AfterStruct:     false
    BeforeElse:      true
    IndentBraces:    false
BreakBeforeBraces: Linux

See the meaning of those keys and their selected values in the ClangFormatStyleOptions document.

Pointer Alignment

Always on the left.

PointerAlignment: Left

Includes

We don't re-sort includes although it is highly recommended to order the headers alphabetically whenever possible.

SortIncludes:    false

Comments

We try not to split comment lines into smaller ones and also we add one space between code and trailing comment.

ReflowComments: false
SpacesBeforeTrailingComments: 1

Spaces

For readability put always spaces before assignment operators.

SpaceBeforeAssignmentOperators: true