[lttng-tools.git] / CodingStyle

LTTng-Tools Coding Style

Author: David Goulet
Last Update: 13/11/2012

Tabs VS Spaces:
-------------

Right, so our two cents in this endless war! This project uses TABS for one
simple reason, the coder can choose whatever size or type his/her indentation
is and can set the prefered coding style by replacing the tabs which each
normally respected IDE/editor can do.

For vim, here is what I used:

  set shiftwidth=4
  set noexpandtab

There is one exception for which  we use space in this project is for enum,
defines and macros values indentation. For instance:

Use space to indent the the value so they fit when reading them all. Same goes
for the #define below.

enum my_enum {
	value1     = 1,
	value289   = 289,
	...
};

#define DEFAULT_VALUE_OF_SOME_SORT   6
#define THE_ANSWER                   42

Use either a single space or tabs to indent the '\' at the end of lines.
Use tabs at the beginning of lines.

Either:

#define a_macro(x) \
	do { \
		fsync(); \
	} while (0)

or

#define a_macro(x)		\
	do {			\
		fsync();	\
	} while (0)

Here is a pretty cool vim macro that will highlight your whitespaces and spaces
before tab. This helps a *LOT* when coding.

" Show trailing whitepace and spaces before a tab:
function MyTrail()
    let no_hl_trail = ["man", "help"]
    if index(no_hl_trail, &ft) >= 0
        return
    endif
    syn match ErrorMsg /\s\+$\| \+\ze\t\|\t\+\ze / containedin=@NoTrail
endfunction
syn cluster NoTrail contains=ALL remove=cComment
autocmd Syntax * call MyTrail()

C Style:
-------------

The coding style used for this project follows the the Linux kernel guide
lines, except that brackets "{", "}" should typically be used even for
single-line if/else statements. Please refer to:

- doc/kernel-CodingStyle.txt (copied from Linux 3.4.4 git tree).

- Linux kernel scripts/checkpatch.pl for a script which verify the patch
  coding style.

For header files, please declare the following in this order:

1) #defines
	- Default values should go in: src/common/defaults.h
	- Macros used across the project: src/common/macros.h

2) Variables
	- No _static_ in a header file! This is madness.
	- Use _extern_ if the global variable is set else where.

3) Function prototype

Furthermore, respect the name spacing of files for each non-static symbol
visiable outside the scope of the C file. For instance, for the utils.c file in
libcommon, every call should be prefixed by "utils_*".

Error handling:
-------------

We ask to use one single return point in a function. For that, we uses the
"goto" statement for the error handling creating one single point for error
handling and return code. See the following example:

int some_function(...)
{
	int ret;
	[...]

	if (ret != 0) {
		goto error;
	}

	[...]
error:
	return ret;
}

Commenting:
-------------

Every function MUST have a comment above it even if the function is trivial.

Please add non-trivial comments/documentation as much as you can in the code.
Poor comments WILL be rejected upon merging so please pay attention to this
details because we do!

If the comments requires more than one line, please format like so:

/*
 * Some comments which requires multiple
 * lines [...]
 */

and on a single line:

/* My comment on a single line. */
Commit	Line	Data
0c8a2a56 MD	1	LTTng-Tools Coding Style
0c8a2a56 MD	2
da1d733c DG	3	Author: David Goulet
	4	Last Update: 13/11/2012
	5
	6	Tabs VS Spaces:
	7	-------------
	8
	9	Right, so our two cents in this endless war! This project uses TABS for one
	10	simple reason, the coder can choose whatever size or type his/her indentation
	11	is and can set the prefered coding style by replacing the tabs which each
	12	normally respected IDE/editor can do.
	13
	14	For vim, here is what I used:
	15
	16	set shiftwidth=4
	17	set noexpandtab
	18
	19	There is one exception for which we use space in this project is for enum,
	20	defines and macros values indentation. For instance:
	21
	22	Use space to indent the the value so they fit when reading them all. Same goes
	23	for the #define below.
	24
	25	enum my_enum {
	26	value1 = 1,
	27	value289 = 289,
	28	...
	29	};
	30
	31	#define DEFAULT_VALUE_OF_SOME_SORT 6
	32	#define THE_ANSWER 42
	33
264ede77 MD	34	Use either a single space or tabs to indent the '\' at the end of lines.
264ede77 MD	35	Use tabs at the beginning of lines.
da1d733c	36
264ede77 MD	37	Either:
	38
	39	#define a_macro(x) \
	40	do { \
	41	fsync(); \
23729762	42	} while (0)
da1d733c	43
264ede77 MD	44	or
	45
	46	#define a_macro(x) \
	47	do { \
	48	fsync(); \
	49	} while (0)
da1d733c DG	50
	51	Here is a pretty cool vim macro that will highlight your whitespaces and spaces
	52	before tab. This helps a LOT when coding.
	53
	54	" Show trailing whitepace and spaces before a tab:
	55	function MyTrail()
	56	let no_hl_trail = ["man", "help"]
	57	if index(no_hl_trail, &ft) >= 0
	58	return
	59	endif
	60	syn match ErrorMsg /\s\+$\\| \+\ze\t\\|\t\+\ze / containedin=@NoTrail
	61	endfunction
	62	syn cluster NoTrail contains=ALL remove=cComment
	63	autocmd Syntax * call MyTrail()
ffb25bd5 DG	64
	65	C Style:
	66	-------------
	67
	68	The coding style used for this project follows the the Linux kernel guide
	69	lines, except that brackets "{", "}" should typically be used even for
	70	single-line if/else statements. Please refer to:
	71
	72	- doc/kernel-CodingStyle.txt (copied from Linux 3.4.4 git tree).
0c8a2a56	73
0c8a2a56 MD	74	- Linux kernel scripts/checkpatch.pl for a script which verify the patch
	75	coding style.
	76
da1d733c DG	77	For header files, please declare the following in this order:
	78
	79	1) #defines
	80	- Default values should go in: src/common/defaults.h
	81	- Macros used across the project: src/common/macros.h
	82
	83	2) Variables
	84	- No _static_ in a header file! This is madness.
	85	- Use _extern_ if the global variable is set else where.
	86
	87	3) Function prototype
	88
	89	Furthermore, respect the name spacing of files for each non-static symbol
	90	visiable outside the scope of the C file. For instance, for the utils.c file in
	91	libcommon, every call should be prefixed by "utils_*".
	92
1f2f4159 DG	93	Error handling:
	94	-------------
	95
	96	We ask to use one single return point in a function. For that, we uses the
	97	"goto" statement for the error handling creating one single point for error
	98	handling and return code. See the following example:
	99
	100	int some_function(...)
	101	{
	102	int ret;
	103	[...]
	104
	105	if (ret != 0) {
	106	goto error;
	107	}
	108
	109	[...]
	110	error:
	111	return ret;
	112	}
	113
ffb25bd5 DG	114	Commenting:
	115	-------------
	116
	117	Every function MUST have a comment above it even if the function is trivial.
	118
1f2f4159 DG	119	Please add non-trivial comments/documentation as much as you can in the code.
	120	Poor comments WILL be rejected upon merging so please pay attention to this
	121	details because we do!
da1d733c DG	122
	123	If the comments requires more than one line, please format like so:
	124
	125	/*
	126	* Some comments which requires multiple
	127	* lines [...]
	128	*/
	129
	130	and on a single line:
	131
	132	/* My comment on a single line. */