应把注释看做和代码一样重要,也要统计到代码量中去。注释除了能够使得代码更易读、清晰外,还能用来生成文档。参见:Doxygen 计划。
分类
按位置分:
1. 位于语句后;2. 变量声明后;3. 予处理后;4. 或单独开始的注释(又有是否从第一行开始的区别)。
按照形式分:
块注释;单行注释(又有是否独立一行或者在代码后面的区别)。
块注释(boxed comments):Boxed comments are defined as those in which the initial `/*' is followed immediately by the character `*', `=', `_', or `-', or those in which the beginning comment delimiter (`/*') is on a line by itself, and the following line begins with a `*' in the same column as the star of the opening delimiter.
以上各个类型的注释可以被indent工具区分和格式化;indent忽略块注释,对齐单行注释等等;
| [提示] |
|
For larger blocks of code that I want to comment and un-comment regularly (eg, debug code), I like to use comments in this style: /* debug code ------------- // echo "This is debug code"; ... // ---------------------- */ You can easily uncoment the whole block by changing the /* to //, and vice versa. |
书写规范
可以用c++风格注释"//",或者用c风格"/* */";
注释最好用英文,英文困难找翻译;
文件头注释结构:为块注释。参见:Doxygen 的风格。
函数前注释结构:为块注释。注名功能。如果参数名不能表达意义,还要说明参数意义。
块注释写法:
/* * a space before * */
或者
/* have a space after three spaces before */
Copyright © 2006 WorldHello 开放文档之源 计划