mirror of https://github.com/xzeldon/htop.git
Tweak style guide wording around single code statements
There was wording about brace-enclosing single code statements being 'strongly encouraged' - this isn't consistently used and IMO it introduces unnecessary noise in otherwise neat, concise code. I've reworded (dropped) this section and also fixed a handful of minor typos while reading this doc a little more carefully.
This commit is contained in:
parent
003f2c06a4
commit
b2a8b2426e
|
@ -78,7 +78,7 @@ Symbol Exports
|
||||||
|
|
||||||
Exports of symbols should be used sparingly.
|
Exports of symbols should be used sparingly.
|
||||||
Thus unless a function you write is intended to become public API of a module you should mark it as `static`.
|
Thus unless a function you write is intended to become public API of a module you should mark it as `static`.
|
||||||
If a function should be public API an appropriate declaration for that function has to be placed in the accompaying header file.
|
If a function should be public API an appropriate declaration for that function has to be placed in the accompanying header file.
|
||||||
|
|
||||||
Please avoid function-like macros, in particular when exporting them in a header file.
|
Please avoid function-like macros, in particular when exporting them in a header file.
|
||||||
They have several downsides (re-evaluation of arguments, syntactic escapes, weak typing) for which usually a better alternative like an actual function exists.
|
They have several downsides (re-evaluation of arguments, syntactic escapes, weak typing) for which usually a better alternative like an actual function exists.
|
||||||
|
@ -107,7 +107,7 @@ Styling the code
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
Now for the style details that can mostly be automated: Indentation, spacing and bracing.
|
Now for the style details that can mostly be automated: Indentation, spacing and bracing.
|
||||||
While there is no definitve code style we use, a set of rules loosely enforced has evolved.
|
While there is no definitive code style we use, a set of rules loosely enforced has evolved.
|
||||||
|
|
||||||
Indentation in the code is done by three (3) spaces. No tabs are used. Ever.
|
Indentation in the code is done by three (3) spaces. No tabs are used. Ever.
|
||||||
|
|
||||||
|
@ -128,41 +128,80 @@ if (very_long_condition &&
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
While braces around single code statements are strongly encouraged, they are usually left out for single statements when only redirecting code flow:
|
Braces around simple single code statements (return, break, continue, goto, trivial assignments) are usually left out.
|
||||||
|
|
||||||
```c
|
```c
|
||||||
if (termination condition)
|
if (answer)
|
||||||
return 42;
|
return 42;
|
||||||
```
|
```
|
||||||
|
|
||||||
Control flow statements and the instruction making up their body should not be put on a single line, i.e. after the condition of an if statement a new line should be inserted and the body indented accordingly.
|
If it helps readability (with several unrelated if statements in a row) or to avoid dangling-else situations braces can be added.
|
||||||
When an if statement uses more than just the true branch it should use braces for all statements that follow:
|
|
||||||
|
Control flow statements and the instruction making up their body should not be put on a single line,
|
||||||
|
i.e. after the condition of an if statement a new line should be inserted and the body indented accordingly.
|
||||||
|
|
||||||
```c
|
```c
|
||||||
if (condition1) {
|
if (answer)
|
||||||
// Some code
|
return 42;
|
||||||
} else if (condition2) {
|
else if (again)
|
||||||
// Some more code
|
continue;
|
||||||
} else {
|
else
|
||||||
// something else
|
goto bowl_of_petunias;
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
While this code style isn't fully consistent in the existing code base it is strongly recommended that new code follows these rules.
|
When the statements that form control flow constructs are complex (e.g. more than just a simple assignment or jump) or need explanatory comments you should use braces.
|
||||||
|
If any block of such a statement uses braces then all blocks of that statement must have braces too.
|
||||||
|
|
||||||
|
```c
|
||||||
|
if ((fd = open(filename, O_RDONLY)) >= 0 &&
|
||||||
|
(amtRead = read(buffer, sizeof(buffer))) > 0) {
|
||||||
|
// Parse the information further ...
|
||||||
|
metric = handleBufferContent(buffer, amtRead);
|
||||||
|
} else {
|
||||||
|
metric = -1;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (fd >= 0)
|
||||||
|
close(fd);
|
||||||
|
```
|
||||||
|
|
||||||
|
While the existing code base isn't fully consistent with this code style isn't fully consistent yet it is strongly recommended that new code follows these rules.
|
||||||
Adapting surrounding code near places you need to touch is encouraged.
|
Adapting surrounding code near places you need to touch is encouraged.
|
||||||
Try to separate such changes into a single, clean-up only commit to reduce noise while reviewing your changes.
|
Try to separate such changes into a single, clean-up only commit to reduce noise while reviewing your changes.
|
||||||
|
|
||||||
|
When writing your code consistency with the surrounding codebase is favoured.
|
||||||
|
|
||||||
|
Don't shy away from leaving (sinlge) blank lines to separate different groups of related statements.
|
||||||
|
They can be a great asset to structure the flow of a method.
|
||||||
|
|
||||||
|
```c
|
||||||
|
int stuff = 0;
|
||||||
|
|
||||||
|
// If asked for gives only half the answer ...
|
||||||
|
if (param)
|
||||||
|
stuff = 21;
|
||||||
|
|
||||||
|
// Compute the answer
|
||||||
|
stuff %= 2;
|
||||||
|
stuff *= 4;
|
||||||
|
stuff *= 5;
|
||||||
|
stuff += !!stuff;
|
||||||
|
stuff *= 2;
|
||||||
|
|
||||||
|
return stuff;
|
||||||
|
```
|
||||||
|
|
||||||
If you want to automate formatting your code, the following command gives you a good baseline of how it should look:
|
If you want to automate formatting your code, the following command gives you a good baseline of how it should look:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
astyle -r -j -xb -s3 -p -xg -c -k1 -W1 \*.c \*.h
|
astyle -r -xb -s3 -p -xg -c -k1 -W1 \*.c \*.h
|
||||||
```
|
```
|
||||||
|
|
||||||
Working with System APIs
|
Working with System APIs
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
Please try to be considerate when using modern platform features.
|
Please try to be considerate when using modern platform features.
|
||||||
While they usually provide quite a performance gain or make your life easier, it is benefitial if `htop` runs on rather ancient systems.
|
While they usually provide quite a performance gain or make your life easier, it is beneficial if `htop` runs on rather ancient systems.
|
||||||
Thus when you want to use such features you should try to have an alternative available that works as a fallback.
|
Thus when you want to use such features you should try to have an alternative available that works as a fallback.
|
||||||
|
|
||||||
An example for this are functions like `fstatat` on Linux that extend the kernel API on modern systems.
|
An example for this are functions like `fstatat` on Linux that extend the kernel API on modern systems.
|
||||||
|
|
Loading…
Reference in New Issue