注释要简单明了。
String userName = null; //用户名
边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。
在必要的地方注释,注释量要适中。注释的内容要清楚、明了,含义准确,防
止注释二义性。保持注释与其描述的代码相邻,即注释的就近原则。
对代码的注释应放在其上方相邻位置,不可放在下面。对数据结构的注释应放在
其上方相邻位置,不可放在下面;对结构中的每个域的注释应放在此域的右方;
同一结构中不同域的注释要对齐。
变量、常量的注释应放在其上方相邻位置或右方。
全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取它以
及存取时注意事项等的说明。
在每个源文件的头部要有必要的注释信息,包括:文件名;版本号;作者;生成日
期;模块功能描述(如功能、主要算法、内部各部分之间的关系、该文件与其它文
件关系等);主要函数或过程清单及本文件历史修改记录等。
/** * Copy Right Information : Neusoft IIT * Project
: eTrain * JDK version used
: jdk1.3.1 * Comments
: config path * Version
: 1.01 * Modification history
:2003.5.1 * Sr Date Modified By Why & What is modified * 1. 2003.5.2 Kevin Gao new **/
在每个函数或过程的前面要有必要的注释信息,包括:函数或过程名称;功能描
述;输入、输出及返回值说明;调用关系及被调用关系说明等
/** * Description :checkout 提款
* @param Hashtable cart info
* @param OrderBean order info
* @return String */
public String checkout(Hashtable htCart,
OrderBean orderBean)
throws Exception{ }
javadoc注释标签语法@author 对类的说明 标明开发该类模块的作者 @version 对类的说明 标明该类模块的版本 @see 对类、属性、方法的说明 参考转向,也就是相关主题 @param 对方法的说明 对方法中某参数的说明@return 对方法的说明 对方法返回值的说明 @exception 对方法的说明 对方法可能抛出的异常进行说明