5. 注释
5.1. 注释的基本约定
注释应该增加代码的清晰度;
保持注释的简洁,不是任何代码都需要注释的,过多的注释反而会影响代码的可读性。
注释不要包括其他的特殊字符。
建议先写注释,后写代码,注释和代码一起完成
如果语句块(比如循环和条件分枝的代码块)代码太长,嵌套太多,则在其结束“}”要加上注释,标志对应的开始语句。如果分支条件逻辑比较复杂,也要加上注释。
在VS2005环境中通过配置工程编译时输出XML文档文件可以检查注释的完整情况,如果注释不完整会报告编译警告;
5.2. 注释类型
5.2.1. 块注释
主要用来描述文件,类,方法,算法等,放在所描述对象的前边。具体格式以IDE编辑器输入“///”自动生成的格式为准,另外再附加我们自定义的格式,如下所列:
/// <Remark>作者,创建日期,修改日期</Remark >
对类和接口的注释必须加上上述标记,对方法可以视情况考虑
5.2.2. 行注释
主要用在方法内部,对代码,变量,流程等进行说明。整个注释占据一行。
5.2.3. 尾随注释
与行注释功能相似,放在代码的同行,但是要与代码之间有足够的空间,便于分清。例:
int m = 4 ; // 注释
如果一个程序块内有多个尾随注释,每个注释的缩进要保持一致。
5.3. 注释哪些部分
项目 | 注释哪些部分 |
参数 | 参数用来做什么 任何约束或前提条件 |
字段/属性 | 字段描述 |
类 | 类的目的 已知的问题 类的开发/维护历史 |
接口 | 目的 它应如何被使用以及如何不被使用 |
局部变量 | 用处/目的 |
成员函数注释 | 成员函数做什么以及它为什么做这个 哪些参数必须传递给一个成员函数 成员函数返回什么 已知的问题 任何由某个成员函数抛出的异常 成员函数是如何改变对象的 包含任何修改代码的历史 如何在适当情况下调用成员函数的例子适用的前提条件和后置条件 |
成员函数内部注释 | 控制结构 代码做了些什么以及为什么这样做 局部变量 难或复杂的代码 处理顺序 |
5.4. 程序修改注释
新增代码行的前后要有注释行说明,对具体格式不作要求,但必须包含作者,新增时间,新增目的。在新增代码的最后必须加上结束标志;
删除代码行的前后要用注释行说明,删除代码用注释原有代码的方法。注释方法和内容同新增;删除的代码行建议用#region XXX #endregion 代码段折叠,保持代码文件干净整洁
修改代码行建议以删除代码行后再新增代码行的方式进行(针对别人的代码进行修改时,必须标明,对于自己的代码进行修改时,酌情进行)。注释方法和内容同新增;