关于编程风格的讨论3

三、注释规范：
1、函数头的注释
对于函数，应该从“功能”，“参数”，“返回值”、“主要思路”、“调用方法”、“日期”六个方面用如下格式注释：
//程序说明开始
//================================================================//
// 功能： 从一个String 中删除另一个String。
// 参数： strByDelete,strToDelete
// （入口） strByDelete: 被删除的字符串（原来的字符串）
// （出口） strToDelete: 要从上个字符串中删除的字符串。
// 返回： 找到并删除返回1，否则返回0。（对返回值有错误编码的要// 求列出错误编码）。
// 主要思路：本算法主要采用循环比较的方法来从strByDelete中找到
// 与strToDelete相匹配的字符串，对多匹配strByDelete
// 中有多个strToDelete子串）的情况没有处理。请参阅：
// 书名......
// 调用方法：......
// 日期：起始日期，如：2000/8/21.9:40--2000/8/23.21:45
//================================================================//
函数名(……)
//程序说明结束
①、对于某些函数，其部分参数为传入值，而部分参数为传出值，所以对参数要详细说明该参数是入口参数，还是出口参数，对于某些意义不明确的参数还要做详细说明（例如：以角度作为参数时，要说明该角度参数是以弧度（PI）,还是以度为单位）,对既是入口又是出口的变量应该在入口和出口处同时标明。等等。
②、函数的注释应该放置在函数的头文件中，在实现文件中的该函数的实现部分应该同时放置该注释。
③、在注释中应该详细说明函数的主要实现思路、特别要注明自己的一些想法，如果有必要则应该写明对想法产生的来由。对一些模仿的函数应该注释上函数的出处。
④、在注释中详细注明函数的适当调用方法，对于返回值的处理方法等。在注释中要强调调用时的危险方面，可能出错的地方。
⑤、对日期的注释要求记录从开始写函数到结束函数的测试之间的日期。
⑥、对函数注释开始到函数命名之间应该有一组用来标识的特殊字符串。
如果算法比较复杂，或算法中的变量定义与位置有关，则要求对变量的定义进行图解。对难以理解的算法能图解尽量图解。
2、变量的注释：
对于变量的注释紧跟在变量的后面说明变量的作用。原则上对于每个变量应该注释，但对于意义非常明显的变量，如：i,j等循环变量可以不注释。
例如： long lLineCount //线的根数。
               
3、文件的注释：
文件应该在文件开头加入以下注释：
/////////////////////////////////////////////////////////////////////
// 工程: 文件所在的项目名。
// 作者：**，修改者：**
// 描述:说明文件的功能。
// 主要函数：…………
// 版本: 说明文件的版本，完成日期。
// 修改: 说明对文件的修改内容、修改原因以及修改日期。
// 参考文献： ......
/////////////////////////////////////////////////////////////////////
为了头文件被重复包含要求对头文件进行定义如下:
#ifndef __FILENAME_H__
#define __FILENAME_H__
其中FILENAME为头文件的名字。
4、其他注释：
在函数内我们不需要注释每一行语句。但必须在各功能模块的每一主要部分之前添加块注释，注释每一组语句，在循环、流程的各分支等，尽可能多加以注释。
其中的循环、条件、选择等位置必须注释。
对于前后顺序不能颠倒的情况，建议在注释中增加序号。
例如：
......
//1、......注释
for (......)
{
}
if(......)
{//......注释
}
else
{//......注释
}
//......注释
switch(......)
{
case: ......// ......注释
......
case: ......// ......注释
......
default: //......注释
......
}
在其他顺序执行的程序中，每隔3-5行语句，必须加一个注释，注明这一段语句所组成的小模块的作用。对于自己的一些比较独特的思想要求在注释中标明。