1*10465441SEvalZero /* This is the official code style of uIP. */
2*10465441SEvalZero
3*10465441SEvalZero /**
4*10465441SEvalZero * \defgroup codestyle Coding style
5*10465441SEvalZero *
6*10465441SEvalZero * This is how a Doxygen module is documented - start with a \defgroup
7*10465441SEvalZero * Doxygen keyword at the beginning of the file to define a module,
8*10465441SEvalZero * and use the \addtogroup Doxygen keyword in all other files that
9*10465441SEvalZero * belong to the same module. Typically, the \defgroup is placed in
10*10465441SEvalZero * the .h file and \addtogroup in the .c file.
11*10465441SEvalZero *
12*10465441SEvalZero * @{
13*10465441SEvalZero */
14*10465441SEvalZero
15*10465441SEvalZero /**
16*10465441SEvalZero * \file
17*10465441SEvalZero * A brief description of what this file is.
18*10465441SEvalZero * \author
19*10465441SEvalZero * Adam Dunkels <[email protected]>
20*10465441SEvalZero *
21*10465441SEvalZero * Every file that is part of a documented module has to have
22*10465441SEvalZero * a \file block, else it will not show up in the Doxygen
23*10465441SEvalZero * "Modules" * section.
24*10465441SEvalZero */
25*10465441SEvalZero
26*10465441SEvalZero /* Single line comments look like this. */
27*10465441SEvalZero
28*10465441SEvalZero /*
29*10465441SEvalZero * Multi-line comments look like this. Comments should prefferably be
30*10465441SEvalZero * full sentences, filled to look like real paragraphs.
31*10465441SEvalZero */
32*10465441SEvalZero
33*10465441SEvalZero #include "uip.h"
34*10465441SEvalZero
35*10465441SEvalZero /*
36*10465441SEvalZero * Make sure that non-global variables are all maked with the static
37*10465441SEvalZero * keyword. This keeps the size of the symbol table down.
38*10465441SEvalZero */
39*10465441SEvalZero static int flag;
40*10465441SEvalZero
41*10465441SEvalZero /*
42*10465441SEvalZero * All variables and functions that are visible outside of the file
43*10465441SEvalZero * should have the module name prepended to them. This makes it easy
44*10465441SEvalZero * to know where to look for function and variable definitions.
45*10465441SEvalZero *
46*10465441SEvalZero * Put dividers (a single-line comment consisting only of dashes)
47*10465441SEvalZero * between functions.
48*10465441SEvalZero */
49*10465441SEvalZero /*---------------------------------------------------------------------------*/
50*10465441SEvalZero /**
51*10465441SEvalZero * \brief Use Doxygen documentation for functions.
52*10465441SEvalZero * \param c Briefly describe all parameters.
53*10465441SEvalZero * \return Briefly describe the return value.
54*10465441SEvalZero * \retval 0 Functions that return a few specified values
55*10465441SEvalZero * \retval 1 can use the \retval keyword instead of \return.
56*10465441SEvalZero *
57*10465441SEvalZero * Put a longer description of what the function does
58*10465441SEvalZero * after the preamble of Doxygen keywords.
59*10465441SEvalZero *
60*10465441SEvalZero * This template should always be used to document
61*10465441SEvalZero * functions. The text following the introduction is used
62*10465441SEvalZero * as the function's documentation.
63*10465441SEvalZero *
64*10465441SEvalZero * Function prototypes have the return type on one line,
65*10465441SEvalZero * the name and arguments on one line (with no space
66*10465441SEvalZero * between the name and the first parenthesis), followed
67*10465441SEvalZero * by a single curly bracket on its own line.
68*10465441SEvalZero */
69*10465441SEvalZero void
code_style_example_function(void)70*10465441SEvalZero code_style_example_function(void)
71*10465441SEvalZero {
72*10465441SEvalZero /*
73*10465441SEvalZero * Local variables should always be declared at the start of the
74*10465441SEvalZero * function.
75*10465441SEvalZero */
76*10465441SEvalZero int i; /* Use short variable names for loop
77*10465441SEvalZero counters. */
78*10465441SEvalZero
79*10465441SEvalZero /*
80*10465441SEvalZero * There should be no space between keywords and the first
81*10465441SEvalZero * parenthesis. There should be spaces around binary operators, no
82*10465441SEvalZero * spaces between a unary operator and its operand.
83*10465441SEvalZero *
84*10465441SEvalZero * Curly brackets following for(), if(), do, and case() statements
85*10465441SEvalZero * should follow the statement on the same line.
86*10465441SEvalZero */
87*10465441SEvalZero for(i = 0; i < 10; ++i) {
88*10465441SEvalZero /*
89*10465441SEvalZero * Always use full blocks (curly brackets) after if(), for(), and
90*10465441SEvalZero * while() statements, even though the statement is a single line
91*10465441SEvalZero * of code. This makes the code easier to read and modifications
92*10465441SEvalZero * are less error prone.
93*10465441SEvalZero */
94*10465441SEvalZero if(i == c) {
95*10465441SEvalZero return c; /* No parentesis around return values. */
96*10465441SEvalZero } else { /* The else keyword is placed inbetween
97*10465441SEvalZero curly brackers, always on its own line. */
98*10465441SEvalZero c++;
99*10465441SEvalZero }
100*10465441SEvalZero }
101*10465441SEvalZero }
102*10465441SEvalZero /*---------------------------------------------------------------------------*/
103*10465441SEvalZero /*
104*10465441SEvalZero * Static (non-global) functions do not need Doxygen comments. The
105*10465441SEvalZero * name should not be prepended with the module name - doing so would
106*10465441SEvalZero * create confusion.
107*10465441SEvalZero */
108*10465441SEvalZero static void
an_example_function(void)109*10465441SEvalZero an_example_function(void)
110*10465441SEvalZero {
111*10465441SEvalZero
112*10465441SEvalZero }
113*10465441SEvalZero /*---------------------------------------------------------------------------*/
114*10465441SEvalZero
115*10465441SEvalZero /* The following stuff ends the \defgroup block at the beginning of
116*10465441SEvalZero the file: */
117*10465441SEvalZero
118*10465441SEvalZero /** @} */
119