From 34484cdaf528083f6d777097b93c74960ab1f48e Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Fri, 17 Aug 2018 14:40:45 +1000 Subject: [PATCH] CODING_STYLE: Update section header format 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 --- CODING_STYLE.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/CODING_STYLE.md b/CODING_STYLE.md index 4fef234ed..80d4096d8 100644 --- a/CODING_STYLE.md +++ b/CODING_STYLE.md @@ -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. @@ -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 `/*`. @@ -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. @@ -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 @@ -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()` @@ -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. @@ -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 @@ -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 @@ -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. @@ -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 - You did write this code or have the right to contribute it to LXC. @@ -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. @@ -501,13 +501,13 @@ rules to use them: Signed-off-by: Christian Brauner ``` -#### 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 @@ -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 @@ -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 -- 2.47.2