uIP 1.0: uip-code-style.c

00001 /* This is the official code style of uIP. */
+00002 
+00003 /**
+00004  * \defgroup codestyle Coding style
+00005  *
+00006  * This is how a Doxygen module is documented - start with a \defgroup
+00007  * Doxygen keyword at the beginning of the file to define a module,
+00008  * and use the \addtogroup Doxygen keyword in all other files that
+00009  * belong to the same module. Typically, the \defgroup is placed in
+00010  * the .h file and \addtogroup in the .c file.
+00011  *
+00012  * @{
+00013  */
+00014 
+00015 /**
+00016  * \file
+00017  *         A brief description of what this file is.
+00018  * \author
+00019  *         Adam Dunkels <adam@sics.se>
+00020  *
+00021  *         Every file that is part of a documented module has to have
+00022  *         a \file block, else it will not show up in the Doxygen
+00023  *         "Modules" * section.
+00024  */
+00025 
+00026 /* Single line comments look like this. */
+00027 
+00028 /*
+00029  * Multi-line comments look like this. Comments should prefferably be
+00030  * full sentences, filled to look like real paragraphs.
+00031  */
+00032 
+00033 #include "uip.h"
+00034 
+00035 /*
+00036  * Make sure that non-global variables are all maked with the static
+00037  * keyword. This keeps the size of the symbol table down.
+00038  */
+00039 static int flag;
+00040 
+00041 /*
+00042  * All variables and functions that are visible outside of the file
+00043  * should have the module name prepended to them. This makes it easy
+00044  * to know where to look for function and variable definitions.
+00045  *
+00046  * Put dividers (a single-line comment consisting only of dashes)
+00047  * between functions.
+00048  */
+00049 /*---------------------------------------------------------------------------*/
+00050 /**
+00051  * \brief      Use Doxygen documentation for functions.
+00052  * \param c    Briefly describe all parameters.
+00053  * \return     Briefly describe the return value.
+00054  * \retval 0   Functions that return a few specified values
+00055  * \retval 1   can use the \retval keyword instead of \return.
+00056  *
+00057  *             Put a longer description of what the function does
+00058  *             after the preamble of Doxygen keywords.
+00059  *
+00060  *             This template should always be used to document
+00061  *             functions. The text following the introduction is used
+00062  *             as the function's documentation.
+00063  *
+00064  *             Function prototypes have the return type on one line,
+00065  *             the name and arguments on one line (with no space
+00066  *             between the name and the first parenthesis), followed
+00067  *             by a single curly bracket on its own line.
+00068  */
+00069 void
+00070 code_style_example_function(void)
+00071 {
+00072   /*
+00073    * Local variables should always be declared at the start of the
+00074    * function.
+00075    */
+00076   int i;                   /* Use short variable names for loop
+00077                               counters. */
+00078 
+00079   /*
+00080    * There should be no space between keywords and the first
+00081    * parenthesis. There should be spaces around binary operators, no
+00082    * spaces between a unary operator and its operand.
+00083    *
+00084    * Curly brackets following for(), if(), do, and case() statements
+00085    * should follow the statement on the same line.
+00086    */
+00087   for(i = 0; i < 10; ++i) {
+00088     /*
+00089      * Always use full blocks (curly brackets) after if(), for(), and
+00090      * while() statements, even though the statement is a single line
+00091      * of code. This makes the code easier to read and modifications
+00092      * are less error prone.
+00093      */
+00094     if(i == c) {
+00095       return c;           /* No parentesis around return values. */
+00096     } else {              /* The else keyword is placed inbetween
+00097                              curly brackers, always on its own line. */
+00098       c++;
+00099     }
+00100   }
+00101 }
+00102 /*---------------------------------------------------------------------------*/
+00103 /*
+00104  * Static (non-global) functions do not need Doxygen comments. The
+00105  * name should not be prepended with the module name - doing so would
+00106  * create confusion.
+00107  */
+00108 static void
+00109 an_example_function(void)
+00110 {
+00111   
+00112 }
+00113 /*---------------------------------------------------------------------------*/
+00114 
+00115 /* The following stuff ends the \defgroup block at the beginning of
+00116    the file: */
+00117 
+00118 /** @} */
+