下一节: , 上一节: , 上级: 编写 C   [目录][索引]


5.2 注释你的工作

每个程序都应该以一个简短说明其用途的注释开始。例如: ‘fmt - 文本简单填充的过滤器’。此注释应位于包含程序 ‘main’ 函数的源文件的顶部。

另外,请在每个源文件的开头写一个简短的注释,说明文件名以及该文件的整体用途的一两行。

请在 GNU 程序中使用英文编写注释,因为英语是几乎所有国家/地区的程序员都可以阅读的语言。如果你的英语写得不好,请尽可能用英语写注释,然后请其他人帮忙重写。如果你不能用英语写注释,请找人与你合作并将你的注释翻译成英语。

请在每个函数上添加注释,说明该函数的作用,它接收的参数类型以及参数可能的值的含义和用途。如果 C 类型以其习惯方式使用,则无需用文字重复 C 参数声明的含义。如果其用法有任何不标准之处(例如,char * 类型的参数实际上是字符串第二个字符的地址,而不是第一个字符的地址),或者任何可能的值不能按预期工作(例如,不保证包含换行符的字符串能够正常工作),请务必说明。

另外,如果存在返回值,请说明其含义。

请在注释中的每个句子末尾添加两个空格,以便 Emacs 句子命令可以正常工作。另外,请写完整的句子并将第一个单词大写。如果小写标识符出现在句子的开头,请不要将其大写!更改拼写会使其成为不同的标识符。如果你不喜欢用小写字母开头一个句子,请用不同的方式编写句子(例如,“标识符 lower-case 是…”)。

如果你使用参数名称来谈论参数值,则对函数的注释会更清晰。变量名本身应为小写,但是当你在谈论值而不是变量本身时,请将其大写。因此,“inode 号 NODE_NUM”,而不是 “一个 inode”。

通常,在函数之前的注释中重复声明函数名称没有意义,因为读者自己可以看到。当注释太长以至于函数本身会超出屏幕底部时,可能会有例外。

每个静态变量也应该有一个注释,像这样

/* Nonzero means truncate lines in the display;
   zero means continue them.  */
int truncate_lines;

每个 ‘#endif’ 都应该有一个注释,除非是不嵌套的短条件(只有几行)。注释应说明正在结束的条件的条件,包括其含义。 ‘#else’ 应该有一个注释,描述以下代码的条件和含义。例如

#ifdef foo
  …
#else /* not foo */
  …
#endif /* not foo */
#ifdef foo
  …
#endif /* foo */

但是,相比之下,对于 ‘#ifndef’,请使用这种方式编写注释

#ifndef foo
  …
#else /* foo */
  …
#endif /* foo */
#ifndef foo
  …
#endif /* not foo */

下一节: , 上一节: , 上级: 编写 C   [目录][索引]