diff options
-rw-r--r-- | CONTRIBUTING.md | 399 |
1 files changed, 399 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6bef7cf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,399 @@ +CONTRIBUTING TO CMOCKA +====================== + +## Merge requests + +cmocka uses gitlab for contributing code and code reviews. You can find the +gitlab repository [here](https://gitlab.com/cmocka/cmocka). + +## Coding conventions + +### Quick Start + +Coding style guidelines are about reducing the number of unnecessary +reformatting patches and making things easier for developers to work together. + +You don't have to like them or even agree with them, but once put in place we +all have to abide by them (or vote to change them). However, coding style should +never outweigh coding itself and so the guidelines described here should be good +enough to follow as they are common and supported by tools and editors. + +The basic style for C code is the Linux Kernel coding style (See +Documentation/CodingStyle in the Kernel source tree). This closely matches what +cmocka developers use already anyways, with a few exceptions as mentioned below. + +To save you the trouble of reading the Linux kernel style guide, here are the +highlights. + +* Maximum Line Width is 80 Characters + The reason is not about people with low-res screens but rather sticking to 80 + columns prevents you from nesting more than one level of if statements or + other code blocks. + +* Use 4 spaces to indent + +* No trailing spaces + Clean up your files before committing. + +* Follow the K&R guidelines. We won't go through all of them here. You have a + copy of "The C Programming Language" anyways right? + + +### Editor Hints + +The projects provides a configuration file for [editorconf](https://editorconfig.org/). + +Most modern code editor provide support for editorconfig either natively or via +a plugin. You should make use of it! + +### FAQ & Statement Reference + +#### Comments + +Comments should always use the standard C syntax. C++ style comments are not +encouraged. + +The lines before a comment should be empty. If the comment directly belongs to +the following code, there should be no empty line after the comment, except if +the comment contains a summary of multiple following code blocks. + +This is good: + +```c + ... + int i; + + /* + * This is a multi line comment, + * which explains the logical steps we have to do: + * + * 1. We need to set i=5, because... + * 2. We need to call complex_fn1 + */ + + /* This is a one line comment about i = 5. */ + i = 5; + + /* + * This is a multi line comment, + * explaining the call to complex_fn1() + */ + ret = complex_fn1(); + if (ret != 0) { + ... + + /** + * @brief This is a doxygen comment. + * + * This is a more detailed explanation of + * this simple function. + * + * @param[in] param1 The parameter value of the function. + * + * @param[out] result1 The result value of the function. + * + * @return 0 on success and -1 on error. + */ + int example(int param1, int *result1); +``` + +This is bad: + +```c + ... + int i; + /* + * This is a multi line comment, + * which explains the logical steps we have to do: + * + * 1. We need to set i=5, because... + * 2. We need to call complex_fn1 + */ + /* This is a one line comment about i = 5. */ + i = 5; + /* + * This is a multi line comment, + * explaining the call to complex_fn1() + */ + ret = complex_fn1(); + if (ret != 0) { + ... + + /*This is a one line comment.*/ + + /* This is a multi line comment, + with some more words...*/ + + /* + * This is a multi line comment, + * with some more words...*/ +``` + +### Indentation, spaces and 80 columns + +To avoid confusion, indentations have to be 4 spaces. Do not use tabs! + +When wrapping parameters for function calls, align the parameter list with the +first parameter on the previous line. For example: + +```c + var1 = foo(long_long_long_long_long_long_long_arg_name1, + long_long_long_long_long_long_long_arg_name2, + long_long_long_long_long_long_long_arg_name3); +``` + +The previous example is intended to illustrate alignment of function parameters +across lines and not as encourage for gratuitous line splitting. Never split a +line before columns 70 - 79 unless you have a really good reason. Be smart +about formatting. + + +### If, switch and code blocks + +Always follow an `if` keyword with a space but don't include additional +spaces following or preceding the parentheses in the conditional. + +Examples: + +```c + // This is good + if (x == 1) + + // This is bad + if ( x == 1 ) + + // This is also bad + if (x==1) +``` + +Yes we have a lot of code that uses the second and third form and we are trying +to clean it up without being overly intrusive. + +Note that this is a rule about parentheses following keywords and not functions. +Don't insert a space between the name and left parentheses when invoking +functions. + +Braces for code blocks used by `for`, `if`, `switch`, `while`, `do..while`, etc should +begin on the same line as the statement keyword and end on a line of their own. +You should always include braces, even if the block only contains one statement. + +**NOTE**: Functions are different and the beginning left brace should be located +in the first column on the next line. + +If the beginning statement has to be broken across lines due to length, the +beginning brace should be on a line of its own. + +The exception to the ending rule is when the closing brace is followed by +another language keyword such as else or the closing while in a `do..while` loop. + +Good examples: + +```c + if (x == 1) { + printf("good\n"); + } + + for (x = 1; x < 10; x++) { + print("%d\n", x); + } + + for (really_really_really_really_long_var_name = 0; + really_really_really_really_long_var_name < 10; + really_really_really_really_long_var_name++) + { + print("%d\n", really_really_really_really_long_var_name); + } + + do { + printf("also good\n"); + } while (1); +``` + +Bad examples: + +```c + while (1) + { + print("I'm in a loop!\n"); } + + for (x=1; + x<10; + x++) + { + print("no good\n"); + } + + if (i < 10) + print("I should be in braces.\n"); +``` + +### Goto + +While many people have been academically taught that goto's are fundamentally +evil, they can greatly enhance readability and reduce memory leaks when used as +the single exit point from a function. But in no world what so ever is a goto +outside of a function or block of code a good idea. + +Good Examples: + +```c + int function foo(int y) + { + int *z = NULL; + int rc = 0; + + if (y < 10) { + z = malloc(sizeof(int)*y); + if (z == NULL) { + rc = 1; + goto done; + } + } + + print("Allocated %d elements.\n", y); + + done: + if (z != NULL) { + free(z); + } + + return rc; + } +``` + +### Initialize pointers + +All pointer variables **MUST** be initialized to `NULL`. History has +demonstrated that uninitialized pointer variables have lead to various bugs and +security issues. + +Pointers **MUST** be initialized even if the assignment directly follows the +declaration, like pointer2 in the example below, because the instructions +sequence may change over time. + +Good Example: + +```c + char *pointer1 = NULL; + char *pointer2 = NULL; + + pointer2 = some_func2(); + + ... + + pointer1 = some_func1(); +``` + +### Typedefs + +cmocka tries to avoid `typedef struct { .. } x_t;` so we do always try to use +`struct x { .. };`. We know there are still such typedefs in the code, but for +new code, please don't do that anymore. + +### Make use of helper variables (aka debugging UX) + +Please try to avoid passing function calls as function parameters in new code. +This makes the code much easier to read and it's also easier to use the "step" +command within gdb. + +Good Example: + +```c + char *name = NULL; + + name = get_some_name(); + if (name == NULL) { + ... + } + + rc = some_function_my_name(name); + ... +``` + + +Bad Example: + +```c + rc = some_function_my_name(get_some_name()); + ... +``` + +Please try to avoid passing function return values to if- or while-conditions. +The reason for this is better handling of code under a debugger. + +Good example: + +```c + x = malloc(sizeof(short) * 10); + if (x == NULL) { + fprintf(stderr, "Unable to alloc memory!\n"); + } +``` + +Bad example: + +```c + if ((x = malloc(sizeof(short)*10)) == NULL ) { + fprintf(stderr, "Unable to alloc memory!\n"); + } +``` + +There are exceptions to this rule. One example is walking a data structure in +an iterator style: + +```c + while ((opt = poptGetNextOpt(pc)) != -1) { + ... do something with opt ... + } +``` + +In general, please try to avoid this pattern. + +### Control-Flow changing macros + +Macros like `STATUS_NOT_OK_RETURN` that change control flow (return/goto/etc) +from within the macro are considered bad, because they look like function calls +that never change control flow. Please do not introduce them. + +### Switch/case indentation + +The `case` should not be indented to avoid wasting too much horizontal space. +When the case block contains local variables that need to be wrapped in braces, +they should not be indented again either. + +Good example: + +```c + switch (x) { + case 0: + do_stuff(); + break; + case 1: { + int y; + do_stuff(); + break; + } + default: + do_other_stuff(); + break; + } +``` + +Bad example: + +```c + switch (x) { + case 0: + do_stuff(); + break; + case 1: + { + int y; + do_stuff(); + break; + } + default: + do_other_stuff(); + break; + } +``` |