From 290cfebd99631fa0edbf8384aa80ebe850ff8643 Mon Sep 17 00:00:00 2001 From: Tim Eckel Date: Tue, 28 Aug 2018 10:30:55 -0400 Subject: [PATCH] Markdown fixes and added style examples --- docs/development/CodingStyle.md | 87 ++++++++++++++++++++++++++------- 1 file changed, 68 insertions(+), 19 deletions(-) diff --git a/docs/development/CodingStyle.md b/docs/development/CodingStyle.md index 7e915b138..434e6bfd2 100644 --- a/docs/development/CodingStyle.md +++ b/docs/development/CodingStyle.md @@ -1,15 +1,15 @@ -#General +# General This document overrides the original Baseflight style that was referenced before. This document has taken inspiration from that style, from Eclipse defaults and from Linux, as well as from some Cleanflight developers and existing code. There are not so many changes from the old style, if you managed to find it. -#Formatting style +# Formatting style -##Indentation +## Indentation K&R indent style with 4 space indent, NO hard tabs (all tabs replaced by spaces). -##Tool support +## Tool support Any of these tools can get you pretty close: Eclipse built in "K&R" style, after changing the indent to 4 spaces and change Braces after function declarations to Next line. @@ -26,21 +26,70 @@ Sometimes, for example, you may want other columns and line breaks so it looks l Note2: The Astyle settings have been tested and will produce a nice result. Many files will be changed, mostly to the better but maybe not always, so use with care. -##Curly Braces +## Curly Braces Functions shall have the opening brace at the beginning of the next line. +``` +int function(int x) +{ + body of function +} +``` All non-function statement blocks (if, switch, for) shall have the opening brace last on the same line, with the following statement on the next line. Closing braces shall be but on the line after the last statement in the block. +``` +if (x is true) { + we do y + ... +} +``` + +``` +switch (action) { + case ADD: + return "add"; + case REMOVE: + return "remove"; + case CHANGE: + return "change"; + default: + return NULL; +} +``` If it is followed by an `else` or `else if` that shall be on the same line, again with the opening brace on the same line. +``` +if (x is true) { + we do y + ... +} else { + we do z + ... +} +``` A single statement after an `if` or an `else` may omit the "unnecessary" braces only when ALL conditional branches have single statements AND you have strong reason to know it will always be that way. +``` +if (x is true) + we do y +else + we do z +``` + +``` +if (x is true) { + we do y + ... +} else { + we do z +} +``` If in doubt, do not omit such "unnecessary" braces. (Adding a statement to a branch will break the logic if the braces are forgotten and otherwise make the PR longer). -##Spaces +## Spaces Use a space after (most) keywords. The notable exceptions are sizeof, typeof, alignof, and __attribute__, which look somewhat like functions (and are usually used with parentheses). So use a space after these keywords: ``` @@ -76,7 +125,7 @@ and no space around the '.' and "->" structure member operators. '*' and '&', when used for pointer and reference, shall have no space between it and the following variable name. -#typedef +# typedef enums with a count should have that count declared as the last item in the enumeration list, so that it is automatically maintained, e.g.: ``` @@ -99,9 +148,9 @@ typedef struct motorMixer_s { ``` the motorMixer_s name is required. -#Variables +# Variables -##Naming +## Naming Generally, descriptive lowerCamelCase names are preferred for function names, variables, arguments, etc. For configuration variables that are user accessible via CLI or similar, all_lowercase with underscore is preferred. @@ -111,7 +160,7 @@ Simple temporary variables with a very small scope may be short where it aligns Such as "i" as a temporary counter in a `for` loop, like `for (int i = 0; i < 4; i++)`. Using "temporaryCounter" in that case would not improve readability. -##Declarations +## Declarations Avoid global variables. Variables should be declared at the top of the smallest scope where the variable is used. @@ -123,7 +172,7 @@ For example to limit variable scope to a single `case` branch. Variables with limited use may be declared at the point of first use. It makes PR-review easier (but that point is lost if the variable is used everywhere anyway). -##Initialisation +## Initialisation The pattern with "lazy initialisation" may be advantageous in the Configurator to speed up the start when the initialisation is "expensive" in some way. In the FC, however, it’s always better to use some milliseconds extra before take-off than to use them while flying. @@ -131,7 +180,7 @@ So don't use "lazy initialisation". An explicit "init" function, is preferred. -##Data types +## Data types Be aware of the data types you use and do not trust implicit type casting to be correct. Angles are sometimes represented as degrees in a float. Sometimes as decidegrees in a uint8_t. @@ -145,9 +194,9 @@ Instead of sin() and cos(), use sin_approx() and cos_approx() from common/math.h Float constants should be defined with "f" suffix, like 1.0f and 3.1415926f, otherwise double conversion might occur. -#Functions +# Functions -##Naming +## Naming Methods that return a boolean should be named as a question, and should not change any state. e.g. 'isOkToArm()'. Methods should have verb or verb-phrase names, like deletePage or save. Tell the system to 'do' something 'with' something. e.g. deleteAllPages(pageList). @@ -167,7 +216,7 @@ void newBiQuadLpf(...); boolean isBiQuadReady(); ``` -##Parameter order +## Parameter order Data should move from right to left, as in memcpy(void *dst, const void *src, size_t size). This also mimics the assignment operator (e.g. dst = src;) @@ -182,7 +231,7 @@ float biQuadFilterApply(float sample, biquad_t *state); void biQuadNewLpf(float filterCutFreq, biquad_t *state, uint32_t refreshRate); ``` -##Declarations +## Declarations Functions not used outside their containing .c file should be declared static (or STATIC_UNIT_TESTED so they can be used in unit tests). Non-static functions should have their declaration in a single .h file. @@ -199,7 +248,7 @@ In the module .c file, and in the test file but nowhere else, put `#define MODUL Note: You can get the same effect by putting the internals in a separate .h file. -##Implementation +## Implementation Keep functions short and distinctive. Think about unit test when you define your functions. Ideally you should implement the test cases before implementing the function. @@ -225,7 +274,7 @@ Use parentheses around each group in logical and mathematical statements, rather than relying on the implicit logic and operator priority. The compiler knows what it’s doing but it should be easy for people too. -#Includes +# Includes All files must include their own dependencies and not rely on includes from the included files or that some other file was included first. Do not include things you are not using. @@ -233,7 +282,7 @@ Do not include things you are not using. "[#pragma once](https://en.wikipedia.org/wiki/Pragma_once)" is preferred over "#include guards" to avoid multiple includes. -#Other details +# Other details No trailing whitespace at the end of lines or at blank lines. Stay within 120 columns, unless exceeding 120 columns significantly increases readability and does not hide information.