C语言代码注释规范

C语言代码注释规范

原则：你想要你的注释告诉别人你的代码做了什么(WHAT)，而不是怎么做的(HOW)

1 首选风格

CASE01：单行注释语义

/* 单行描述. */
vaddr = -1; 

CASE02：单行注释变量

union {
    /** @儿子: 单行描述. */
    int 儿子;
};

CASE03：多行注释语义

/*
 * This is the preferred style for multi-line
 * comments in the Linux kernel source code.
 * Please use it consistently.
 *
 * Description:  A column of asterisks on the left side,
 * with beginning and ending almost-blank lines.
 */

CASE04：多行注释结构体

/**
 * struct 张三 - 简短描述.
 * @张三: 成员张三.
 */
struct 张三 {
      int 张三;
      /**
       * @李四: 成员李四.
       */
      int 李四;
      /**
       * @王五: 成员王五.
       *
       * 此处，成员描述可以为好几段.
       */
};

2 说明场景

CASE01：定义函数

/**
 * 函数名() - 函数简要说明.
 * @参数1: 描述第一个参数.
 * @参数2: 描述第二个参数.
 *        可以为参数提供一段
 *        多行描述.
 *
 * 更详细的描述，进一步讨论函数 函数名(), 这可能对使用或修改它的人有用.
 * 以空注释行开始, 内部可以包含空注释行.
 *
 * 详细描述可以有多个段落.
 *
 * Context: 描述函数是否可以休眠, 它需要、释放或期望持有什么锁.
 *          可以写多行.
 * Return: 描述函数返回值.
 *
 * 返回值描述也可以有多个段落,
 * 并且应该放在注释块的末尾.
 */

CASE02：定义结构体类型

/**
 * struct 结构体名 - 简要描述.
 * @成员1: 成员1描述.
 * @成员2: 成员2描述.
 *           可以为成员提供
 *           多行描述.
 *
 * 结构体的描述.
 */

CASE03：条件编译

#ifdef CONFIG_SOMETHING
...
#endif /* CONFIG_SOMETHING */

3 参考资料

• kernel-doc.html
• C 语言最佳实践之可读性