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 代码段折叠，保持代码文件干净整洁
修改代码行建议以删除代码行后再新增代码行的方式进行（针对别人的代码进行修改时，必须标明，对于自己的代码进行修改时，酌情进行）。注释方法和内容同新增；