Mirror/betaflight
1
0
Fork 0
mirror of https://github.com/betaflight/betaflight.git synced 2025-07-25 17:25:20 +03:00
Code Issues Wiki Activity

Markdown fixes and added style examples

Browse source
This commit is contained in:
Tim Eckel 2018-08-28 10:30:55 -04:00 • committed by GitHub
parent 9ef901f251
commit 290cfebd99
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 68 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

87
docs/development/CodingStyle.md
View file

@ -1,15 +1,15 @@
#General # General
This document overrides the original Baseflight style that was referenced before. 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. 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. 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). 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: 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. 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. 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. 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. 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. 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 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. 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. 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). (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). 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: 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. '*' 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, 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.: so that it is automatically maintained, e.g.:
``` ```
@ -99,9 +148,9 @@ typedef struct motorMixer_s {
``` ```
the motorMixer_s name is required. the motorMixer_s name is required.
#Variables # Variables
##Naming ## Naming
Generally, descriptive lowerCamelCase names are preferred for function names, variables, arguments, etc. 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. 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++)`. 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. Using "temporaryCounter" in that case would not improve readability.
##Declarations ## Declarations
Avoid global variables. Avoid global variables.
Variables should be declared at the top of the smallest scope where the variable is used. 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). 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. 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. 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. 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. 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. 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. 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 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). 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(); boolean isBiQuadReady();
``` ```
##Parameter order ## Parameter order
Data should move from right to left, as in memcpy(void *dst, const void *src, size_t size). 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;) 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); 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). 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. 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. Note: You can get the same effect by putting the internals in a separate .h file.
##Implementation ## Implementation
Keep functions short and distinctive. 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. 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. 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. 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. 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. 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. "[#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. 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. Stay within 120 columns, unless exceeding 120 columns significantly increases readability and does not hide information.