Skip to content

Commit

Permalink
CODING_STYLE: Update section header format
Browse files Browse the repository at this point in the history
Currently for section headings we use fourth level markdown heading
level (####).  We do not have levels two or three.

We can use standard incremental levels for heading adornments i.e

1) =========
2) ##
3) ###
ect.

Since this document is likely referenced by maintainers when guiding new
contributors it can save maintainer time to be able to quickly reference
a section in the coding stlye guide.  If we add numbers to each heading
(like the kernel stlye guide) then maintainers can say:

   Nice patch, please see section 3 of the coding style guide and ...

So, this patch makes two changes

- Use incremental level heading adornments
- Add a number to each section heading

Signed-off-by: Tobin C. Harding <me@tobin.cc>
  • Loading branch information
tcharding authored and Christian Brauner committed Dec 10, 2018
1 parent f2872db commit 34484cd
Showing 1 changed file with 24 additions and 24 deletions.
48 changes: 24 additions & 24 deletions CODING_STYLE.md
Expand Up @@ -12,7 +12,7 @@ It can be accessed online too:

https://www.kernel.org/doc/html/latest/process/coding-style.html

#### General Notes
## 1) General Notes

- The coding style guide refers to new code. But legacy code can be cleaned up
and we are happy to take those patches.
Expand Down Expand Up @@ -76,11 +76,11 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html
initializations will not be correct. In such cases please refer to the coding
style here.
#### Only Use Tabs
## 2) Only Use Tabs
- LXC uses tabs.
#### Only use `/* */` Style Comments
## 3) Only use `/* */` Style Comments
- Any comments that are added must use `/* */`.
- All comments should start on the same line as the opening `/*`.
Expand All @@ -97,13 +97,13 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html
*/
```
#### Try To Wrap At 80chars
## 4) Try To Wrap At 80chars
- This is not strictly enforced. It is perfectly valid to sometimes
overflow this limit if it helps clarity. Nonetheless, try to stick to it
and use common sense to decide when not to.
#### Error Messages
## 5) Error Messages
- Error messages must start with a capital letter and must **not** end with a
punctuation sign.
Expand All @@ -115,22 +115,22 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html
WARN("\"/dev\" directory does not exist. Proceeding without autodev being set up");
```
#### Return Error Codes
## 6) Return Error Codes
- When writing a function that can fail in a non-binary way try to return
meaningful negative error codes (e.g. `return -EINVAL;`).
#### All Unexported Functions Must Be Declared `static`
## 7) All Unexported Functions Must Be Declared `static`
- Functions which are only used in the current file and are not exported
within the codebase need to be declared with the `static` attribute.
#### All Exported Functions Must Be Declared `extern` In A Header File
## 8) All Exported Functions Must Be Declared `extern` In A Header File
- Functions declared in header files (`*.h`) should use the `extern` keyword.
- Functions declared in source files (`*.c`) should not use the `extern` keyword.
#### Declaring Variables
## 9) Declaring Variables
- variables should be declared at the top of the function or at the beginning
of a new scope but **never** in the middle of a scope
Expand Down Expand Up @@ -173,7 +173,7 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html
}
```
#### Functions Not Returning Booleans Must Assign Return Value Before Performing Checks
## 10) Functions Not Returning Booleans Must Assign Return Value Before Performing Checks
- When checking whether a function not returning booleans was successful or not
the returned value must be assigned before it is checked (`str{n}cmp()`
Expand All @@ -197,7 +197,7 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html
continue;
```
#### Non-Boolean Functions That Behave Like Boolean Functions Must Explicitly Check Against A Value
## 11) Non-Boolean Functions That Behave Like Boolean Functions Must Explicitly Check Against A Value
- This rule mainly exists for `str{n}cmp()` type functions. In most cases they
are used like a boolean function to check whether a string matches or not.
Expand Down Expand Up @@ -251,17 +251,17 @@ https://www.kernel.org/doc/html/latest/process/coding-style.html
}
```
#### Do Not Use C99 Variable Length Arrays (VLA)
## 12) Do Not Use C99 Variable Length Arrays (VLA)
- They are made optional and there is no guarantee that future C standards
will support them.
#### Use Standard libc Macros When Exiting
## 13) Use Standard libc Macros When Exiting
- libc provides `EXIT_FAILURE` and `EXIT_SUCCESS`. Use them whenever possible
in the child of `fork()`ed process or when exiting from a `main()` function.
#### Use `goto`s
## 14) Use `goto`s
`goto`s are an essential language construct of C and are perfect to perform
cleanup operations or simplify the logic of functions. However, here are the
Expand Down Expand Up @@ -335,12 +335,12 @@ rules to use them:
}
```
#### Use Booleans instead of integers
## 15) Use Booleans instead of integers
- When something can be conceptualized in a binary way use a boolean not
an integer.
#### Cleanup Functions Must Handle The Object's Null Type And Being Passed Already Cleaned Up Objects
## 16) Cleanup Functions Must Handle The Object's Null Type And Being Passed Already Cleaned Up Objects
- If you implement a custom cleanup function to e.g. free a complex type
you declared you must ensure that the object's null type is handled and
Expand Down Expand Up @@ -382,7 +382,7 @@ rules to use them:
}
```
#### Cast to `(void)` When Intentionally Ignoring Return Values
## 17) Cast to `(void)` When Intentionally Ignoring Return Values
- There are cases where you do not care about the return value of a function.
Please cast the return value to `(void)` when doing so.
Expand Down Expand Up @@ -429,11 +429,11 @@ rules to use them:
}
```
#### Use `for (;;)` instead of `while (1)` or `while (true)`
## 18) Use `for (;;)` instead of `while (1)` or `while (true)`
- Let's be honest, it is really the only sensible way to do this.
#### Use The Set Of Supported DCO Statements
## 19) Use The Set Of Supported DCO Statements
- Signed-off-by: Random J Developer <random@developer.org>
- You did write this code or have the right to contribute it to LXC.
Expand All @@ -459,7 +459,7 @@ rules to use them:
helped you solve a problem or had a clever idea do not silently claim it by
slapping your Signed-off-by underneath. Be honest and add a Suggested-by.
#### Commit Message Outline
## 20) Commit Message Outline
- You **must** stick to the 80chars limit especially in the title of the commit
message.
Expand Down Expand Up @@ -501,13 +501,13 @@ rules to use them:
Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
```
#### Use `_exit()` To Terminate `fork()`ed Child Processes
## 21) Use `_exit()` To Terminate `fork()`ed Child Processes
- When `fork()`ing off a child process use `_exit()` to terminate it instead of
`exit()`. The `exit()` function is not thread-safe and thus not suited for
the shared library which must ensure that it is thread-safe.
#### Keep Arrays of `struct`s Aligned Horizontally When Initializing
## 22) Keep Arrays of `struct`s Aligned Horizontally When Initializing
- Arrays of `struct`s are:
```C
Expand Down Expand Up @@ -614,7 +614,7 @@ rules to use them:
};
```
#### Use `strlcpy()` instead of `strncpy()`
## 23) Use `strlcpy()` instead of `strncpy()`
When copying strings always use `strlcpy()` instead of `strncpy()`. The
advantage of `strlcpy()` is that it will always append a `\0` byte to the
Expand All @@ -624,7 +624,7 @@ Unless you have a valid reason to accept truncation you must check whether
truncation has occurred, treat it as an error, and handle the error
appropriately.
#### Use `strlcat()` instead of `strncat()`
## 24) Use `strlcat()` instead of `strncat()`
When concatenating strings always use `strlcat()` instead of `strncat()`. The
advantage of `strlcat()` is that it will always append a `\0` byte to the
Expand Down

0 comments on commit 34484cd

Please sign in to comment.