2019独角兽企业重金招聘Python工程师标准>>> 
代码注释是对代码设计者、代码阅读者以及系统间调用提供了有效的帮助，最大限度的提高团队开发合作效率增强系统的可维护性。我们追求简化，不是为了写注释而写注释。
（快速使用请直接看六、七、八）
一、原则：
1.注释形式统一
使用统一的注释风格，不要随意创建新的注释风格。
2.注释准确简洁
内容要简单、明了，防止注释的多义性，错误的注释不但无益反而有害。
二、注释条件：
1.基本注释（必须加）
a)类（接口）的注释
b)构造函数的注释
c)方法的注释
d)全局变量的注释
e)字段/属性的注释
注:Bean对象的getter、setter方法不需加注释。
2.局部注释（必须加）
a)典型算法必须有注释。
b)在代码不明晰处必须有注释。
c)在代码修改处加上修改标识的注释。
d)在循环和逻辑分支组成的代码中加注释。
e)为他人提供的接口必须加详细注释。
三、注释格式：
1.单行(single-line)注释：“//……”
2.块(block)注释：“/*……*/”
3.文档注释：“/**……*/”
四、javadoc 注释标签语法
@author对类的说明标明开发该类模块的作者
@version对类的说明标明该类模块的版本
@see对类、属性、方法的说明参考转向，也就是相关主题
@param对方法的说明对方法中某参数的说明
@return对方法的说明对方法返回值的说明
@exception对方法的说明对方法可能抛出的异常进行说明
五、注释：
1.类（接口）注释
/**
* @ClassName: Test
* @Description:TODO(这里用一句话描述这个类的作用)
* @authorjarek
* @date 2015年11月6日下午2:25:41
* @Copyright ? 2015上海通善互联网金融信息服务有限公司
*/
publicclass Testextends TextMessageSender {
.....
}
2.构造方法注释
/**
* (这里用一句话描述这个构造函数的作用)
*
*/
public Test() {
super();
// TODO Auto-generated constructor stub
}
/**
* (这里用一句话描述这个构造函数的作用)
*
* @param userId
* @param userName
*/
public Test(StringuserId, String userName) {
super();
this.userId =userId;
this.userName =userName;
}
3.方法注释
/**
* @method checkUser(这里用一句话描述这个方法的作用)
* @return boolean
* @authorjarek
* @date 2015年11月6日下午3:26:33
*/
publicboolean checkUser(StringuserId) throws Exception {
returntrue;
}
4.全局变量注释
/** 公司代码 */
privatefinal Stringcompay = "ts";
5.字段/属性注释
// 用户ID
private StringuserId;
// 用户名称
private StringuserName;
6.局部注释
publicstaticvoidensureQueueExists(SQSConnectionconnection, String queueName)throwsJMSException {
AmazonSQSMessagingClientWrapper client = connection.getWrappedAmazonSQSClient();
/**
* 检测队列是否存在，不存在则创建
*/
if( !client.queueExists(queueName) ) {
client.createQueue(queueName );
}
}
......
｝
六、代码修改注释
注释格式如下：
修改人，修改时间，UC编码，迭代编码修改说明（原因、内容）可以单行简短注释
如：
//jarek 2015年11月9日上午11:36:18 @UC_XXXX @In 变更说明（原因、修改内容）
代码改动量小时，在修改代码行前追加注释
对于改动量大时，可以在方法前追加注释
对整个java类变化大时，可以重新追加类注释
七、导入模版(模版文件见文档附件)
* @return ${return_type}
* @author ${user}
* @date ${date} ${time}
*//**@ClassName: ${type_name}
* @Description: TODO(这里用一句话描述这个类的作用)
* @author ${user}
* @date ${date} ${time}
* @Copyright © ${year}上海通善互联网金融信息服务有限公司
*//**(这里用一句话描述这个构造函数的作用)
* ${tags}
*//**
* ${bare_field_name}
*
* @return the ${bare_field_name}
* @since 1.0.0
*/
/**
* ${tags}
* ${see_to_target}
*//** (这里用一句话描述这个方法的作用)
* ${see_to_overridden}
*//**
* ${field}:${todo}（用一句话描述这个变量表示什么）
*
* @since 1.0.0
*/
/**
* @param ${param} the ${bare_field_name} to set
*/
八、使用：
只要导入在eclips中导入注释模版即可
通过 /** +回车或 mc +alt+/ 会调出所有模版，提供方便快速注释的功能。