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