Merge branch 'styleguide-tweak' of https://github.com/natoscott/htop into natoscott-styleguide-tweak

1 files changed, 53 insertions, 14 deletions

diff --git a/docs/styleguide.md b/docs/styleguide.md
index 4c0ac1f5..22c5157f 100644
--- a/docs/styleguide.md
+++ b/docs/styleguide.md
@@ -78,7 +78,7 @@ Symbol Exports
 
 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`.
-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.
 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.
-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.
 
@@ -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
-if (termination condition)
+if (answer)
    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.
-When an if statement uses more than just the true branch it should use braces for all statements that follow:
+If it helps readability (with several unrelated if statements in a row) or to avoid dangling-else situations braces can be added.
+
+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
+if (answer)
+   return 42;
+else if (again)
+   continue;
+else
+   goto bowl_of_petunias;
+```
+
+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 (condition1) {
-   // Some code
-} else if (condition2) {
-   // Some more code
+if ((fd = open(filename, O_RDONLY)) >= 0 &&
+   (amtRead = read(buffer, sizeof(buffer))) > 0) {
+   // Parse the information further ...
+   metric = handleBufferContent(buffer, amtRead);
 } else {
-   // something else
+   metric = -1;
 }
+
+if (fd >= 0)
+   close(fd);
 ```
 
-While this code style isn't fully consistent in the existing code base it is strongly recommended that new code follows these rules.
+While the existing code base isn't fully consistent with this code style yet it is strongly recommended that new code follows these rules.
 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.
 
+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:
 
 ```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
 ------------------------
 
 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.
 
 An example for this are functions like `fstatat` on Linux that extend the kernel API on modern systems.