Contiki 源码风格

/**
 * \defgroup coding-style Coding style
 *
 * This is how a Doxygen module is documented - start with a \defgroup
 * Doxygen keyword at the beginning of the file to define a module,
 * and use the \addtogroup Doxygen keyword in all other files that
 * belong to the same module. Typically, the \defgroup is placed in
 * the .h file and \addtogroup in the .c file.
 *
 * @{
 */

/**
 * \file
 *         A brief description of what this file is.
 * \author
 *         Adam Dunkels <adam@dunkels.com>
 *
 *         Every file that is part of a documented module has to have
 *         a \file block, else it will not show up in the Doxygen
 *         "Modules" * section.
 */

/* Single line comments look like this. */

/*
 * Multi-line comments look like this. Comments should prefferably be
 * full sentences, filled to look like real paragraphs.
 */

#include "contiki.h"

/*
 * Make sure that non-global variables are all maked with the static
 * keyword. This keeps the size of the symbol table down.
 */
static int flag;

/*
 * All variables and functions that are visible outside of the file
 * should have the module name prepended to them. This makes it easy
 * to know where to look for function and variable definitions.
 *
 * Put dividers (a single-line comment consisting only of dashes)
 * between functions.
 */
/*---------------------------------------------------------------------------*/
/**
 * \brief      Use Doxygen documentation for functions.
 * \param c    Briefly describe all parameters.
 * \return     Briefly describe the return value.
 * \retval 0   Functions that return a few specified values
 * \retval 1   can use the \retval keyword instead of \return.
 *
 *             Put a longer description of what the function does
 *             after the preamble of Doxygen keywords.
 *
 *             This template should always be used to document
 *             functions. The text following the introduction is used
 *             as the function's documentation.
 *
 *             Function prototypes have the return type on one line,
 *             the name and arguments on one line (with no space
 *             between the name and the first parenthesis), followed
 *             by a single curly bracket on its own line.
 */
void
code_style_example_function(void)
{
  /*
   * Local variables should always be declared at the start of the
   * function.
   */
  int i;                   /* Use short variable names for loop
                  counters. */

  /*
   * There should be no space between keywords and the first
   * parenthesis. There should be spaces around binary operators, no
   * spaces between a unary operator and its operand.
   *
   * Curly brackets following for(), if(), do, and case() statements
   * should follow the statement on the same line.
   */
  for(i = ; i < ; ++i) {
    /*
     * Always use full blocks (curly brackets) after if(), for(), and
     * while() statements, even though the statement is a single line
     * of code. This makes the code easier to read and modifications
     * are less error prone.
     */
    if(i == c) {
      return c;           /* No parentesis around return values. */
    } else {              /* The else keyword is placed inbetween
                 curly brackers, always on its own line. */
      c++;
    }
  }
}
/*---------------------------------------------------------------------------*/
/*
 * Static (non-global) functions do not need Doxygen comments. The
 * name should not be prepended with the module name - doing so would
 * create confusion.
 */
static void
an_example_function(void)
{

}
/*---------------------------------------------------------------------------*/

/* The following stuff ends the \defgroup block at the beginning of
   the file: */

/** @} */

contiki/docs/code-style.c

一、模块 ：

\defgroup 定义一个模块，一般在.h文件。

/** @} */ 和@{对应。

\addtogroup 加到某个模块，一般在.c文件。

/** @} */ 和@{对应。

\file 文件，每个需要生成文档的文件，都要添加这个标号。

/**
 * \file
 *         A brief description of what this file is.
 * \author
 *         Adam Dunkels <adam@dunkels.com>
 *
 *         Every file that is part of a documented module has to have
 *         a \file block, else it will not show up in the Doxygen
 *         "Modules" * section.
 */

二、变量

不是全局变量的要添加static，限于该文件可见。

/*
* Make sure that non-global variables are all maked with the static
* keyword. This keeps the size of the symbol table down.
*/
static int flag;

局部变量要在函数statement之前定义

  /*
   * Local variables should always be declared at the start of the
   * function.
   */
  int i;                   /* Use short variable names for loop
                  counters. */

三、函数

函数或者变量，对外可见的话，要在函数名前添加模块名，这样可方便知道到哪查看函数或变量的定义。

函数和函数之间用一行只有-的注释来分隔开。

/*
* All variables and functions that are visible outside of the file
* should have the module name prepended to them. This makes it easy
* to know where to look for function and variable definitions.
*
* Put dividers (a single-line comment consisting only of dashes)
* between functions.
*/
/*---------------------------------------------------------------------------*/

函数原型及功能说明

返回值在一行

名字和参数在一行，第一个参数和 '('  不用空格隔开

下一行为{

/**
* \brief Use Doxygen documentation for functions.
* \param c Briefly describe all parameters.
* \return Briefly describe the return value.
* \retval 0 Functions that return a few specified values
* \retval 1 can use the \retval keyword instead of \return.
*
* Put a longer description of what the function does
* after the preamble of Doxygen keywords.
*
* This template should always be used to document
* functions. The text following the introduction is used
* as the function's documentation.
*
* Function prototypes have the return type on one line,
* the name and arguments on one line (with no space
* between the name and the first parenthesis), followed
* by a single curly bracket on its own line.
*/

静态函数不用添加文档注释，也不要添加模块名字，因为静态函数只在本文件可见。

四、语句

关键词和第一个 ‘(’ 不用空格隔开

二元操作符要有空格隔开

一元操作符不用空格隔开

‘{’ 要和 if() for() do case() 等语句在同一行

在 if() for() while() 等语句后都要添加{}，即使只有一行代码，方便阅读和后续修改。

else要被 } { 包围，并自同一行

/*
   * There should be no space between keywords and the first
   * parenthesis. There should be spaces around binary operators, no
   * spaces between a unary operator and its operand.
   *
   * Curly brackets following for(), if(), do, and case() statements
   * should follow the statement on the same line.
   */
  for(i = ; i < ; ++i) {
    /*
     * Always use full blocks (curly brackets) after if(), for(), and
     * while() statements, even though the statement is a single line
     * of code. This makes the code easier to read and modifications
     * are less error prone.
     */
    if(i == c) {
      return c;           /* No parentesis around return values. */
    } else {              /* The else keyword is placed inbetween
                 curly brackers, always on its own line. */
      c++;
    }
  }
}