规则:
1：一般情况下，源程序有效注释量必须在20％以上。
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。
2：说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。
示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/*************************************************
Copyright (C), 1988-1999, Tech. Co., Ltd.
File name: // 文件名
Author:
Version:
Date: // 作者、版本及完成日期
Description:// 用于详细说明此程序文件完成的主要功能，与其他模块
// 或函数的接口，输出值、取值范围、含义及参数间的控
// 制、顺序、独立或依赖等关系
Others:// 其它内容的说明
Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明
1. ....
History:// 修改历史记录列表，每条修改记录应包括修改日期、修改
// 者及修改内容简述
1. Date:
Author:
Modification:
2. ...
*************************************************/
3：源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。
示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/************************************************************
Copyright (C), 1988-1999, Tech. Co., Ltd.
FileName: test.cpp
Author:
Version :
Date:
Description:// 模块描述
Version:// 版本信息
Function List: // 主要函数及其功能
1. -------
History:// 历史修改记录
<author> <time> <version > <desc>
David96/10/121.0build this moudle
***********************************************************/
说明：Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。History是修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述。
4：函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。
示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/*************************************************
Function: // 函数名称
Description:// 函数功能、性能等的描述
Calls: // 被本函数调用的函数清单
Called By: // 调用本函数的函数清单
Table Accessed: // 被访问的表（此项仅对于牵扯到数据库 *** 作的程序）
Table Updated: // 被修改的表（此项仅对于牵扯到数据库 *** 作的程序）
Input: // 输入参数说明，包括每个参数的作
// 用、取值说明及参数间关系。
Output:// 对输出参数的说明。
Return:// 函数返回值的说明
Others:// 其它说明
*************************************************/
5：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
6：注释的内容要清楚、明了，含义准确，防止注释二义性。
说明：错误的注释不但无益反而有害。
7：避免在注释中使用缩写，特别是非常用缩写。
说明：在使用缩写时或之前，应对缩写进行必要的说明。
8：注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
示例：如下例子不符合规范。
例1：
/* get replicate sub system index and net indicator */
repssn_ind = ssn_data[index].repssn_index
repssn_ni = ssn_data[index].ni
例2：
repssn_ind = ssn_data[index].repssn_index
repssn_ni = ssn_data[index].ni
/* get replicate sub system index and net indicator */
应如下书写
/* get replicate sub system index and net indicator */
repssn_ind = ssn_data[index].repssn_index
repssn_ni = ssn_data[index].ni
9：对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。
示例：
/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000
#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */
10：数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。
示例：可按如下形式说明枚举/数据/联合结构。
/* sccp interface with sccp user primitive message name */
enum SCCP_USER_PRIMITIVE
{
N_UNITDATA_IND, /* sccp notify sccp user unit data come */
N_NOTICE_IND, /* sccp notify user the No.7 network can not */
/* transmission this message */
N_UNITDATA_REQ, /* sccp user's unit data transmission request*/
}
11：全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。
示例：
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */ // 变量作用、含义
/* 0 － SUCCESS 1 － GT Table error */
/* 2 － GT error Others － no use */ // 变量取值范围
/* only function SCCPTranslate() in */
/* this modual can modify it, and other */
/* module can visit it through call */
/* the function GetGTTransErrorCode() */// 使用方法
BYTE g_GTTranErrorCode
12：注释与所描述内容进行同样的缩排。
说明：可使程序排版整齐，并方便注释的阅读与理解。
示例：如下例子，排版不整齐，阅读稍感不方便。
void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */
CodeBlock Two
}
应改为如下布局。
void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */
CodeBlock Two
}
13：将注释与其上面的代码用空行隔开。
示例：如下例子，显得代码过于紧凑。
/* code one comments */
program code one
/* code two comments */
program code two
应如下书写
/* code one comments */
program code one
/* code two comments */
program code two
14：对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。
15：对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。
示例（注意斜体加粗部分）：
case CMD_UP:
ProcessUp()
break
case CMD_DOWN:
ProcessDown()
break
case CMD_FWD:
ProcessFwd()
if (...)
{
...
break
}
else
{
ProcessCFW_B() // now jump into case CMD_A
}
case CMD_A:
ProcessA()
break
case CMD_B:
ProcessB()
break
case CMD_C:
ProcessC()
break
case CMD_D:
ProcessD()
break
...
建议:
1：避免在一行代码或表达式的中间插入注释。
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
2：通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
3：在代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：如下注释意义不大。
/* if receive_flag is TRUE */
if (receive_flag)
而如下的注释则给出了额外有用的信息。
/* if mtp receive a message from links */
if (receive_flag)
4：在程序块的结束行右方加注释标记，以表明某程序块的结束。
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。
示例：参见如下例子。
if (...)
{
// program code
while (index <MAX_INDEX)
{
// program code
} /* end of while (index <MAX_INDEX) */ // 指明该条while语句结束
} /* end of if (...)*/ // 指明是哪条if语句结束
5：注释格式尽量统一，建议使用"/* …… */"。
6：注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。
说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。
对于代码注释来说，在不同的教程或者原则中有不同的规定或者解释。有的原则是需要使用JavaDoc来描写每个方法，而有的原则是要求每一个属性标注命名。我愿意相信每一份看起来不那么妥当的注释都是出于一些善意的目的，这就是注释的本质:
对未能自行解释的代码做出解释。
在进行代码工作的时候我们多多少少会有一些陈旧的、与业务无关的逻辑在代码中运行。有时候并不是一个变量名或者一个方法名就能阐述清楚产品同学所期望的业务内容。我们希望将代码外的逻辑也加入到其中，但是一篇长篇大论的注释似乎也不那么妥当，所以对于注释我一般会加入一个约束的条件：
尽可能精简地描述当前方法、属性未能解释的逻辑。
那么这个约束中的关键词是：精简、当前、未能解释。这是我现在的理解，如果有更好的见解也希望可以联系我进行沟通。当然这些关键词在后文中也会进行解释。
对于代码的退化这个概念在很多的领域之中都有阐述。而一种比较主流的观点是：应用程序的生产寿命可能为3-5年。当然这个大限将至无法使用的定义是有很大空间的。但是这个说法的主要思想是：代码随着业务的迭代开发，会逐渐地降低可维护性，直到它的生命终结。代码是这样，对应的代码注释也是这样的。
对于代码注释来说，不知道大家是否经历过类似的内容:
他们可能都是痛苦的回忆，但是这就是刚刚所描述的，注释的退化。
对于代码来说，我们有许多的方法论、设计模式来尽可能地将代码的职责划分清晰从而延长。而对于注释来说，我认为最大的方法是“ 不写注释 ”（关于这个在后面的章节中会再次讨论）。
只要不写注释，注释就不会有问题。之所以会有这个问题的原因是，通常人们在调整业务逻辑后无法完美地维护注释。而更多情况是当代码逻辑发生变动了之后，注释直接编成了业务谜题中的一部分，开发人员不仅要在破败不堪的代码中梳理逻辑，还同时要小心错误注释发出的诱惑。
同时，当代码发生退化逐渐变得不可控的时候，比起重新抽象代码结果，看起来以一段注释来描述新的逻辑比较简单。但是带来的问题就是：“在尝试用注释弥补代码逻辑的问题”。显然注释无法帮你抽象代码，只是看起来将问题爆发的时间延后了（甚至引入了更严重的问题）。
那么“不写注释”的思想换一个角度来描述的话就是：让代码注释自己。这是一种习惯，举个最简单的例子:
可以改为:
哪怕是调整为:
可以看出来，第二种方法是指用对象内的方法，如果order只是一个自动生成的实体对象或者是一种值对象的话，那么也可以使用第三种方法。
这样调整的好处就是，用代码自身去描述逻辑，从而尽量“不写注释”。
对于不写注释的这个论点，除了代码自动解释以外，还有很多情况下的注释都是不那么合适的。
那么我对简单方法的定义是，如果方法实际逻辑(刨除括号部分)5-7行（我自己的标准）则可以认为是一个简单方法。读这样的方法的注释反而可能比直接看代码还来得复杂。
对于一些无法直接用语言进行直接描述的逻辑，我觉得要不就直接不要写注释了，让他们直接进行代码的阅读比较好。否则有歧义性的注释反而会误导人员进行理解。当然，对于我自己而言，内部项目中对于不便与用文字精确描述的逻辑，我会贴上wiki的连接进行图文描述。这样对于不希望阅读的开发人员注释不会产生干扰，而同时图文配合又便于理解。
JavaDoc标准要求对每个参数进行定义，但是这样带来的问题就是一些足够简明的参数的注释本身就是冗余的，例如:
尽管看起来很完美，但是它本身没有任何意义。所以对于代码中具有自解释性的变量名称（它们本应该具有自解释性），JavaDoc的注释其实是非必要的。
行为注释在在IDE里面行为的注释会导致代码的可读性大大降低，有的可能会在很长一段代码之后，有的则可能在很短的代码之后，他们的格式是不容易统一的，所以在现在广为流传的阿里巴巴开发手册中就明确的加上了在上一行中注释。
事实上，我还在用用户署名，因为之前创建了文件模版之后就一直沿用了。不过原则上来说，java文件署名的这个习惯是源于早期的代码版本控制并不是很发达的时代。而现代版本控制中，文件的来世今生都由版本控制来进行了，所以事到如今的用户署名已经没有意义了。
注释掉的代码就应该直接删除，否则会对后续的人员产生干扰。人们可能会下意识地与注释掉的代码产生逻辑交互，并且认为这部分由其保留的目的而并不动。和上条一样，在版本控制比较发达的今天，已经被注释的代码如果有其特殊的功能作用的话，应该是由一个单独的分支进行保护，而非一段会干扰到正常业务开发的注释代码。
如果注释所表达的功能与当前的方法无关的话，说明这部分的注释并不是完全为当前的方法服务的。那么它就不应该出现在这里，也许在一个另外的readme或者是wiki文档中才是它更好的位置。
如果将非当前功能的注释添加到方法上的话，那这里就会造成：如果要理解注释，就要去知道注释的上下文，那么这部分的注释本身就需要额外的说明，就与注释本身的功能背道而驰了。
尽管我们希望不使用注释，直接让代码就能完成逻辑解释的功能，但有时候代码确实是无法完全胜任。一般来说，以下的情况下是适用于进行注释补充的。
有时候，对于额外的程序外的背景描述，是可以补充的。这样可以在你尽管理解了代码逻辑，但是不知道他为什么这么实现的时候增加了额外的判断条件。也可以帮你确认是由于什么考虑才成为了当前的代码逻辑，比如：
这样的话尽管你可能不认同之前人员实现的方法，但是至少可以知道他的目的，从而判断是否可以进行业务调整。
代码是临时的在代码中进行的笔记。尽管是注释，但却和单纯的代码注释的意义不一样，可以进行标记。但一定要记得定时的处理TODO，否则大家的敏感度会降低。
警告如果业务或者功能方法在特定的情况下不应该执行。这些情况往往是组合了一些业务情况的信息，或者是实际生产情况下产生bug的记录。这样的注释将可以确实地提高解决问题的效率。但是要注意的是这部分的内容可能会遭受到代码腐化的影响。题外话：idea里面可以设置不同颜色的"@xxx"的标签，例如我新建了"@ATTENTION"从而将后续的内容调整成了紫色以提供相应的警示作用。
事实上，对于上面的观点很多观点，也是大多数全球程序员的观点。而中国自有我大国之情：便是语言问题。上文所说的代码自解释性的前提是对代码的表达意思了解得准确。而会想一下你对一些领域模型进行起名的时候，有多少是通过谷歌翻译、或者百度结果而查出来的？对于这种得到的名词来说，很难定义它是准确地描述了开发人员意图的变量名称。所以如果是这种前提的话，我认为对于指定对象中的字段、或者指定使用的参数、局部变量等名称，是可以酌情在属性、方法名上对指定的名字进行约束解释，以便由于方法名称和其他的概念混淆。简单点来说：
对于没有信心使用英文精准描述的名称，还是用注释进行约束较好。
本文主要内容来自《Clean Code》中注释一章。阅读感悟主要是文章中的内容有一些是针对超长工作经验的老油条说的，他们可能由于过往的习惯导致注释问题，而这一点在中国互联网存在的问题不明显；中国的母语区别导致代码的自解释性降低，学好英语还是非常重要的呀。
欢迎分享，转载请注明来源：内存溢出
微信扫一扫
支付宝扫一扫
评论列表（0条）