uIP 1.0: uip-code-style.c

- Main Page
- Modules
- Data Structures
- Files
- Examples

# 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 /** @} */