注释规范

一、意义

        注释是程序设计者和程序阅读者之间通信的重要手段。应用注释规范对于软件本身和程序开发人员尤其重要。好的注释规范尽可能减少维护成本，并且几乎没有如何一个软件，在其整个生命周期中，都由最初开发人员来维护。好的注释规范可以改善程序的可读性，可以让开发人员尽快而彻底地理解新的代码。好的规范可以最大限度提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力。

二、javadoc注解元素

 

二、Javadoc注释

 

a) 类、接口和抽象类：必须指明类作者(@author)，版本(@version)，描述和参考（@see）。描述主要包括功能和约束条件，算法则需解释

b) 属性：作用和注意事项，如果有范围需要指明属性范围。如果是常量属性，则需通过{@value}指明值

c) 函数（构造函数）：必须描述函数功能，如果有必须指明参数、返回值和抛出异常。该函数是算法则必须额外添加算法描述。参数含义、及其它任何约束或前提条件。

 

三、程序注释

a) 注释形式统一，必须使用统一的样式，不要试图引进新的规范

b) 注释内容要简单明了，不存在多义性

c) 注释位置，保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。

d) 多余的注释，描述程序功能和程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序如何工作的低级注释则不利于读、写和修改，是不必要的，也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释，避免多余的或不适当的注释出现。 

e) 必加的注释，典型算法必须有注释。在代码不明晰或不可移植处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的

f) 当代码比较长，特别是有多重嵌套时，为了使层次清晰，应当在一些段落的结束处加注释（在闭合的右花括号后注释该闭合所对应的起点），注释不能写得很长，只要能表示是哪个控制语句控制范围的结束即可，这样便于阅读。 

g) 注释连同代码不能超过120字。

h) 局部（中间）变量注释： 主要变量必须有注释，无特别意义的情况下可以不加注释。 

i) 全局变量注释： 要有较详细的注释，包括对其功能、取值范围、哪些函数或者过程存取以及存取时注意事项等的说明。 

j) 方法内部注释： 控制结构，代码做了些什么以及为什么这样做，处理顺序等，特别是复杂的逻辑处理部分，要尽可能的给出详细的注释。 

四、修改注释（可以视情况而定）

如果模块只进行部分少量代码的修改时，则每次修改须添加以下注释： 

//Rewriter 

//Version：版本号（要和类中的版本号对应） Start1： 

/* 原代码内容*/ 

//End1： 

将原代码内容注释掉，然后添加新代码使用以下注释： 

//Added by 

//Version：版本号（要和类中的版本号对应） Start2： 

//End2： 

如果模块输入输出参数或功能结构有较大修改，则每次修改必须添加以下(要备份原来版本源文件) 

注释： 

//Version:版本号.ID（ID是自增，如：v1.2.1）

//Depiction：<对此修改的描述> 

//Writer：修改者中文名 

//Added by  Start2： 

//End2

参考：http://gyhgc.iteye.com/blog/225039