Blame doc/CODING.RULES

Packit 5e46da
=== Coding Rules ===
Packit 5e46da
Packit 5e46da
The project CodingStyle must be adhered to unless there is a reasonable reason for doing otherwise (to be discussed
Packit 5e46da
with dev lead beforehand).
Packit 5e46da
Packit 5e46da
Packit 5e46da
Packit 5e46da
== Coding Style ==
Packit 5e46da
Packit 5e46da
This project uses the '''K&R''' variant '''1TBS''' (One True Base Style) which is the standard of the linux kernel
Packit 5e46da
and many open source projects.
Packit 5e46da
Packit 5e46da
This style can be described as follows (adapted from wikipedia):
Packit 5e46da
Packit 5e46da
The K&R style keeps the first opening brace on the same line as the control statement, indents the statements within
Packit 5e46da
the braces, and puts the closing brace on the same indentation level as the control statement (on a line of its own).
Packit 5e46da
Functions, however, are braced distinctly from statements; an opening function brace is placed on the line following
Packit 5e46da
the declaration, at the same indentation level as the declaration. The opening brace for function declarations is an
Packit 5e46da
exception on the basic rule.
Packit 5e46da
Packit 5e46da
The 1TBS variant expects that the constructs that allow insertions of new code lines are on separate lines, and
Packit 5e46da
constructs that prohibit insertions are on a single line. This principle is amplified by bracing every if, else,
Packit 5e46da
while, etc. -even single-line conditionals- so that insertion of a new line of code anywhere is always "safe".
Packit 5e46da
Packit 5e46da
Advantages of this style are that the beginning brace does not require an extra line by itself; and the ending brace
Packit 5e46da
lines up with the statement it conceptually belongs to. One disadvantage of this style is that the ending brace of a
Packit 5e46da
block takes up an entire line by itself, which can be partially resolved in if/else blocks and do/while blocks.
Packit 5e46da
Packit 5e46da
E.g.:
Packit 5e46da
Packit 5e46da
int main(int argc, char *argv[])
Packit 5e46da
{
Packit 5e46da
    ...
Packit 5e46da
    while (x == y) {
Packit 5e46da
        something();
Packit 5e46da
        something_else();
Packit 5e46da
        if (x < 0) {
Packit 5e46da
            printf("Negative");
Packit 5e46da
            negative(x);
Packit 5e46da
        } else {
Packit 5e46da
            printf("Positive");
Packit 5e46da
            positive(x);
Packit 5e46da
        }
Packit 5e46da
        something_more();
Packit 5e46da
        if (x == 1) {
Packit 5e46da
            x_eq_1(x, y);
Packit 5e46da
	} else {
Packit 5e46da
            x_neq_1(x, y);
Packit 5e46da
	}
Packit 5e46da
    }
Packit 5e46da
    final_thing();
Packit 5e46da
    ...
Packit 5e46da
}
Packit 5e46da
Packit 5e46da
We use 4-space indentation (which is popular amoungst many media projects) so please make sure your code editor
Packit 5e46da
is configured accordingly. No TABs, no trailing white space !
Packit 5e46da
Packit 5e46da
Packit 5e46da
Packit 5e46da
== Function naming ==
Packit 5e46da
Packit 5e46da
 * all lowercase as in linux kernel code
Packit 5e46da
Packit 5e46da
 * functions that might be called by other sections of code to be put in section header
Packit 5e46da
Packit 5e46da
 * functions that will only be called by code within their own section to be prefixed with an underscore and forward
Packit 5e46da
   declared within the .c itself
Packit 5e46da
Packit 5e46da
Packit 5e46da
Packit 5e46da
== Memory allocation and pointers ==
Packit 5e46da
Packit 5e46da
All pointers bust be defined as NULL in their declaration if possible (and if not - e.g. when present in a struct -
Packit 5e46da
immediately in the first function to use the struct).
Packit 5e46da
Packit 5e46da
All allocated memory must be freed with the X_FREE() macro. This is to make sure that we never have double-free
Packit 5e46da
runtime issues.
Packit 5e46da
Packit 5e46da
So:
Packit 5e46da
Packit 5e46da
struct a {
Packit 5e46da
    char *x, *y;
Packit 5e46da
};
Packit 5e46da
Packit 5e46da
void foo()
Packit 5e46da
{
Packit 5e46da
    struct a a;
Packit 5e46da
    char *z = NULL;
Packit 5e46da
Packit 5e46da
    a.x = NULL;
Packit 5e46da
    a.y = NULL;
Packit 5e46da
Packit 5e46da
    ...
Packit 5e46da
    a.x = malloc(10);
Packit 5e46da
    z = malloc(10);
Packit 5e46da
    ...
Packit 5e46da
Packit 5e46da
    X_FREE(a.x);
Packit 5e46da
    X_FREE(a.y);    // this won't throw an error because we stuck to the NULL definition rule!
Packit 5e46da
    X_FREE(z);
Packit 5e46da
}
Packit 5e46da