Consistent and Minimal

Most important rules: Be consistent. Be minimal. Read these sections carefully.

Text file layout

Tab size is 8 spaces.
Shift width (indentation) is 4 spaces.
Column width 79 char, so it fits well with 80 col terminal.
Indentation is always one shift-width(4):

Braces

open and close braces of a section should be on the same level.

Breaking a long line

when breaking up a long line, it should continue with one shift-width for indentation

if for while statement

if/for/while statement that takes more than one line should always have braces; same thing goes when the then/loop part is more than one line

Functions prototypes space

function prototypes should be spaced like function calls

Unneeded casting

do not cast void *, this is unneeded in C.

Do not cast function prototypes

do not cast function prototypes - if the implementation changes in the future, it will be hard to discover. the only exception is typecasting xxx_free() functions (functions from type void xxx_close(xxx_t *xxx)).

switch statement

switch statements should have the case on the same level, no space before ':'.
if the case is one line, then one space after ':'.
never 'break' in 'default'.

Spaces

no space between function name and opening parenthesis
no space between opening parenthesis and first parameter
one space after comma:

one space after reserved words before the opening parenthesis:

'then' part of if statement

'then' part of if statement should be in a separete line:
reason: allows to debug the if and see when it is run.

else if

else if statements should be on the same level at the starting if reason: this is similar to switch statement

return

return statements should not have parentheses and should not have a space after them:

do not use unneeded parentheses in expressions

do not call return at the end of a function returning void

should not separate with more than one blank line between sections, functions etc.

structure and enum definitions

structure and enum definitions, itializations should open { at the same line. it is recommended that the name will end with a _t. typedef the struct, to make it easy to use later on.

Comments

prefer C++ comments to C comments

/* close all files */ fclose(fp); // close all files fclose(fp);

Comments aligned

comments should be aligned as the code they comment, or one space after the end of the line.

Multiline comments

comments which occupy more than one line should adhere to the following guidline

Comments ident

Comment should never be ident more the 4 spaces even in structures.
If longer, put the comment at the line above.

Comments of XXX

Comments of XXX should be <keywords>: <comment>. multiple names should be separated with a '/':

for or while loop

common sense should come into play when deciding whether to use for or while loops

while for if without a statement

Spacing

One space after assignment

put one space before and after an assignment.

Assignment in for loop

if it is in a for loop, you can skip the spaces. if you skip one of the spaces, skip both

No space before statement seperator

don't put a space before a statement seperator, put one after it

No space after increment/decrement

don't put a space after increment and decrement. increment after the value, not before.

Don't increment, set or change value of variable inside a function call

for loops assign inside a statement

in for loops, when there is a function that gets the next element, it should be done once (inside the step condition):
assign inside a statement:

truth value in if/for/while

when assigning in a truth value (if for while), use parentheses. This helps eliminating compilation warnings.

string initialization and zero termination

in string initialization and zero termination, you must use 0

function return values

• in functions returning a pointer, return NULL on fail.
• in functions that only have success/fail, use 0 for success and -1 for failure (instead of TRUE and FALSE).
• in functions with many error reasons, use negative values for the reason.
• functions returning and integer that is "small" and positive, return -1 if fails. if 0 is an invalid success value, then you may choose to return 0 for failure.
• in functions that can return any integer, you have two options:
  • if its error is not important, then check if you can logically return 0 or anything else that will bring desired behaviour.
  • if the error indication is important, then add another parameter to pass the error.
• functions that return boolean values (is_big, is_directory, is_download) should return 0 for false and non 0 for true, according to standard K&R C. (not to use FALSE and TRUE).

implement error handling only once

implement error handling only once, by setting all variables to zero at the begining, and performing a goto to exit the function. If no error handling is required (i.e. no memory to release, no files to close, etc) - plain return should be used

Do not use goto for anything other then error handling.

naming conventions

code will be in UNIX notation. UNIX names should not include the data type, rather the meaning of the information in the data.

checking function return values

functions that return int or a pointer will be checked without comparing, if they return 0 or non 0.

static functions when possible

functions

when possible use static when declaring functions which are only in scope for the file they're in. functions which are not declared static are considered a part of the API. if init() is the only function calling calc_init_time() then:

variables

allocating

when allocating or using a structre, use ZALLOC/calloc or BZERO its elements.
try using BZERO instead of memset().

Check constructor initing

perfer to check constructor initing in same line of calling the constructor. this allows variable re-use, and makes it more obvious the constructor may fail.

macros

functions instead of macros

try using functions instead of macros. in most cases there is no performance problem.

macro names

macro names should normally be all upper case, with normal spacing as rest of code

macro multi arguments

using ## for macro multi arguments (x...) will result in a compilation error when using gcc 3.3.x and up

macros with more than one statement

macros that are more than one statement long should be encapsulated by do-while(0). this enables using them inside if-else statements:

// example usage: if (cond) DO_A_AND_B; else do_something_else();

static functions in header instead of macros

if you need a function, but you don't want a library to link with, then you can use static functions in the header file instead of macros

Don't use forward declarations

don't use forward declarations unless they are necessary. Instead change the order so the caller is below the callee.

Prefer native c data types instead of OS specific data types.

Double inclusion protection

at the begining of a file, add double inclusion protection, where the file path and name is surrounted by two underscores before and after; a slash and a dot are translated to an underscore.

#ifndef __UTIL_ZERR_H__ #define __UTIL_ZERR_H__ // the pkg/util/zerr.h content comes here #endif

Files terminate

files should terminate with a carriage return
reason: compilers can ignore lines that are not terminated by a CR.

Nested #if

nested #if directives should not be indented (neither the # character nor the directive itself, regardless of how complex they are).

#endif comments

You can put an #endif a comment telling to what if it belongs if there is a large gap between the #if and its corresponding #endif.

enum

enum should be in the same line if they are very short

enum {STATUS_OK=DEVIOCTL_NOERROR, STATUS_FAIL=-1}; enum { CMD_NONE=0, CMD_END=1, WP_WORD=14, }; enum { CMD_NONE = 0, CMD_END = 1, WP_WORD = 14, };

enums should have values attached

all enum lines be comma terminated

all enum lines be comma terminated - this makes the enum extensible.
only separate the last line, if it is meant to never be surpassed.

Spaces only after commas

enum in same line should have spaces only after commas

Put the pointer next to the variable

Dynamic allocation only when needed

use stack allocation for local variables of const size. use dynamic allocation only when needed.

defined()

only use the defined() macro when you have a complex expression or in #elif.
If you find that you do need to use the defined() macro for more than one flag, see if the 2 flags can be grouped under another one new flag.

#ifdef SPECIFIC_OS order

how to do and #ifdef SPECIFIC_OS what comes first, the right order is

#ifdef LINUX ..... #elif defined(SOLARIS) ..... #elif defined(VXWORKS) ..... #elif defined(OS2) ..... #elif defined(WIN95) ..... #elif defined(WINNT) ..... #elif defined(WINCE) ..... #endif

C++ data members names

in C++ classes give data members names starting with m_

class find_t { int m_index; char *m_text; };

functions

functions used in one C file: should be implemented static, and a declaration in the C file should only be added if used before implemented. (example: queue_locate_any()).
functions used out of the C file ('global'): should be declared in the H file. (example: queue_locate_item() and queue_activate_operation()). structures used in one C file: should be declared inside the C file. (example: sched_operation_t).
a pointer to the structure is needed out of the C file: a forward declaration should be in the H file, and the full decleration in the C file. (example: sched_queue_t).
the structure's members are needed out of the C file: declare it in the H file. (no example below).

// in H file typedef struct sched_queue_t sched_queue_t; sched_queue_t *queue_locate_item(char *name); void queue_activate_operation(sched_queue_t *sched); // in C file typedef struct { char *operation; char *user; } sched_operation_t; sched_operation_t valid_operations[] = { {"ls", "root"}, {"rm", "anonymous"}, {NULL, NULL} }; struct sched_queue_t { struct sched_queue_t *next; char *name; char *operation; int expire; }; sched_queue_t *the_queue; static sched_queue_t *queue_locate_any(char *name) { sched_queue_t *search; for (search = the_queue; search && strcmp(search->name, name); search = search->next); return search; } sched_queue_t *queue_locate_item(char *name) { sched_queue_t *search = queue_locate_any(name); // check if already expired if (expire>get_current_time()) { queue_remove(search); return NULL; } return search; }

object oriented naming

the data structure should be the name of the object with _t at the end.
functions should all start with the object name, then operation starting with a verb.

typedef struct { the_objects_data_members; } xxx_t; // use _alloc and _free if it only allocates memory, and does not do // "active" operations xxx_t *xxx_alloc(initialization_param); void xxx_free(xxx_t *xxx); // use _open and _close if it does active stuff like call many functions, // register events, IOCTLs etc... xxx_t *xxx_open(initialization_param); void xxx_close(xxx_t *xxx); // use _init and _uninit if it does not allocate the xxx_t structure, only // its sons - i.e. xxx_alloc can be a simple zalloc() while xxx_init // can be a simple ZEROM(). xxx_uninit frees data structures that the xxx_t // points to, without freeing xxx_t itself void xxx_init(xxx_t *xxx, initialization_param); void xxx_uninit(xxx_t *xxx); // methods on the xxx object char *xxx_get_by_index(xxx_t *xxx, int index); int xxx_get_by_name(xxx_t *xxx, char *name); char **xxx_get_name_list(xxx_t *xxx); void xxx_set(xxx_t *xxx, char *name); void xxx_set_nofail(xxx_t *xxx, char *name);

linked lists

simple linked lists always have a 'next' variable as the first structure member.

functions for list are xxx_free() and xxx_list_free()

the xxx_yyy (xxx is object name and yyy is function name), for functions on the object, NOT on list of objects.
the xxx_list_yyy is for functions on the list of objects (such as xxx_list_add, xxx_list_remove).

// sample functions: xxx_t *xxx_dup(xxx_t *p); // retunes a duplicated object void xxx_copy(xxx_t *dst, xxx_t *src); // copy object's data void xxx_free(xxx_t *p); // free the object xxx_t *xxx_alloc(init_data....); // creates a new initialized object void xxx_init(xxx_t *p, init_data....); // initializes an object void xxx_uninit(xxx_t *p, init_data....); // un-initializes an object // frees the list. list now is destroyed void xxx_list_free(xxx_t *xxx_list); // adds an object to the list void xxx_list_add(xxx_t **xxx_list, xxx_t *new_elem);

Don't implement add and remove functions

normally, we should not implement add and remove functions (xxx_list_add and xxx_list_remove). these should only be implemented if there is specific added value (specific code) that needs to be done in addition to adding to the list.
when scanning lists in order to add/remove elements, a pointer to pointer should be used.

typedef struct file_t { struct file_t *next; char *name; } file_t; // frees a single file object file_free(file_t *p) { if (p->name) free(p->name); free(p); } // frees the whole list of object file_list_free(file_t *p) { while (p) { file_t *tmp = p->next; file_free(p); p = tmp; } }

free() handles NULL

free() also handles NULL, so no need for 'if ()' before it

exit a function with a negative value

to exit a function with a negative value, to indicate an error, and send a log message, you may use the fact that zerr() returns negative value

// GOOD but a little long: if (ioctl()<0) { zerr_f(LERR, "failed ioctl()"); return -1; } // GOOD short and neat: if (ioctl()<0) return zerr_f(LERR, "failed ioctl()");

constant strings longer than one line

constant strings longer than one line should be closed on each line by a quote and opened again on the next line. words should have the space after them on the same line.

Dont use const char *

Don't use 'const char *' (or 'char const *') in code. It is impossible to integrate code written with consts into a large system.

Zero parameters functions

Functions that accept zero parameters should be defined as accepting void

Compile time arrays

Compile time arrays should be terminated with a NULL (or -1 when 0 is valid) element, and not by calculating the size of the the array using sizeof.

Trivial

Trivial > >= < <= == != expressions should not have spaces around them.
Trivial expressions examples: a_var, array[3].var[1], sizeof(xxx), (x + 1) Pointers -> are not counted as trivial expressions for > >= < <=, since its hard to read x->y>z, while its not hard to read x->y==z.

Empty lines

Don't put empty lines between code inside functions. If you want to separate code fragments, put a comment line.

Templates

Module foo in pkg/bar/foo.c & foo.h. All files should follow this exact example.
#include "config.h" must be first in the *.c file to make sure the features configuration affect all the rest of the files.
Header files must be self contained, i.e. - they must be able to compile without relying on another include line to come before them.
Therefore #include "foo.h" must be immediately after to make sure foo.h compiles stand alone without any dependency on includes before it.
_BEGIN_EXTERN_C and _END_EXTERN_C allow the code to link to C++.

pkg/bar/foo.c template

// LICENSE_CODE ZON #include "config.h" #include "foo.h" ... put here minimal includes required by foo.c ... ... put here your code ...

pkg/bar/foo.h template

// LICENSE_CODE ZON #ifndef __BAR_FOO_H__ #define __BAR_FOO_H__ #include "config.h" ... put here minimal includes required by foo.h ... _BEGIN_EXTERN_C ... put here functions, structures and other definitions ... _END_EXTERN_C #endif

#include "foo.h"

Use #include "foo.h" for headers in the same directory as the source including them.
Use #include "path_to_foo/foo.h" for headers in other directories, where path_to_foo is relative to root pkg directory.
Use #include <foo.h> for external system files.

Temporary disabling test

When temporary disabling test code that fail:
Do not indent the code of the disabled tests.

If it is only one test

If it is only one test (one statement), then don't use { } even if the statement is written in 2 lines

Open { on the same if() line