Java注释模板 约定不等于承诺〃 2022-01-13 03:53 221阅读 0赞 [2019独角兽企业重金招聘Python工程师标准>>> ][2019_Python_] ![hot3.png][] 代码注释是对代码设计者、代码阅读者以及系统间调用提供了有效的帮助,最大限度的提高团队开发合作效率增强系统的可维护性。我们追求简化,不是为了写注释而写注释。 (快速使用请直接看六、七、八) 一、原则: 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**(这里用一句话描述这个类的作用) \* **@author**jarek \* **@date** 2015年11月6日下午2:25:41 \* **@Copyright** ? 2015上海通善互联网金融信息服务有限公司 \*/ **publicclass** Test **extends** TextMessageSender \{ ..... \} 2.构造方法注释 /\*\* \* (这里用一句话描述这个构造函数的作用) \* \*/ **public** Test() \{ **super**(); // **TODO** Auto-generated constructor stub \} /\*\* \* (这里用一句话描述这个构造函数的作用) \* \* **@param** userId \* **@param** userName \*/ **public** Test(String userId, String userName) \{ **super**(); **this**.userId = userId; **this**.userName = userName; \} 3.方法注释 /\*\* \* **@method** checkUser(这里用一句话描述这个方法的作用) \* **@return** boolean \* **@author**jarek \* **@date** 2015年11月6日下午3:26:33 \*/ **publicboolean** checkUser(String userId) **throws** Exception \{ **returntrue**; \} 4.全局变量注释 /\*\* 公司代码 \*/ **privatefinal** String compay = "ts"; 5.字段/属性注释 // 用户ID **private** String userId; // 用户名称 **private** String userName; 6.局部注释 **publicstaticvoid**ensureQueueExists(SQSConnection connection, String queueName)**throws**JMSException \{ AmazonSQSMessagingClientWrapper client = connection.getWrappedAmazonSQSClient(); /\*\* \* 检测队列是否存在,不存在则创建 \*/ **if**( !client.queueExists(queueName) ) \{ client.createQueue( queueName ); \} \} ...... } 六、代码修改注释 注释格式如下: 修改人,修改时间,UC编码,迭代编码修改说明(原因、内容)可以单行简短注释 如: //jarek 2015年11月9日上午11:36:18 @UC\_XXXX @In 变更说明(原因、修改内容) 代码改动量小时,在修改代码行前追加注释 对于改动量大时,可以在方法前追加注释 对整个java类变化大时,可以重新追加类注释 七、导入模版(模版文件见文档附件) ![30182923_8tlu.jpg][] <?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="false" context="methodcomment\_context" deleted="false" description="Comment for non-overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodcomment" name="methodcomment">/\*\*@method $\{enclosing\_method\}(这里用一句话描述这个方法的作用) \* @return $\{return\_type\} \* @author $\{user\} \* @date $\{date\} $\{time\} \*/</template><template autoinsert="false" context="typecomment\_context" deleted="false" description="Comment for created types" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.typecomment" name="typecomment">/\*\*@ClassName: $\{type\_name\}&\#13; \* @Description: TODO(这里用一句话描述这个类的作用) &\#13; \* @author $\{user\} &\#13; \* @date $\{date\} $\{time\} &\#13; \* @Copyright © $\{year\}上海通善互联网金融信息服务有限公司&\#13; \*/</template><template autoinsert="false" context="constructorcomment\_context" deleted="false" description="Comment for created constructors" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorcomment" name="constructorcomment">/\*\*(这里用一句话描述这个构造函数的作用) \* $\{tags\} \*/</template><template autoinsert="false" context="gettercomment\_context" deleted="false" description="Comment for getter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.gettercomment" name="gettercomment">/\*\* \* $\{bare\_field\_name\} \* \* @return the $\{bare\_field\_name\} \* @since 1.0.0 \*/ </template><template autoinsert="true" context="delegatecomment\_context" deleted="false" description="Comment for delegate methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.delegatecomment" name="delegatecomment">/\*\* \* $\{tags\} \* $\{see\_to\_target\} \*/</template><template autoinsert="false" context="overridecomment\_context" deleted="false" description="Comment for overriding methods" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.overridecomment" name="overridecomment">/\*\* (这里用一句话描述这个方法的作用) \* $\{see\_to\_overridden\} \*/</template><template autoinsert="false" context="fieldcomment\_context" deleted="false" description="Comment for fields" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.fieldcomment" name="fieldcomment">/\*\* \* $\{field\}:$\{todo\}(用一句话描述这个变量表示什么) \* \* @since 1.0.0 \*/ </template><template autoinsert="false" context="filecomment\_context" deleted="false" description="Comment for created Java files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.filecomment" name="filecomment"/><template autoinsert="true" context="settercomment\_context" deleted="false" description="Comment for setter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/\*\* \* @param $\{param\} the $\{bare\_field\_name\} to set \*/</template></templates> ![30182923_hTDy.jpg][] <?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><template autoinsert="true" context="java" deleted="false" description="代码变更注释模版" enabled="true" name="mc">//$\{user\} $\{date\} $\{time\} @UC\_XXXX @In 变更说明(原因、修改内容)</template></templates> 八、使用: 只要导入在eclips中导入注释模版即可 通过 /\*\* +回车或 mc +alt+/ 会调出所有模版,提供方便快速注释的功能。 转载于:https://my.oschina.net/zhanghaiyang/blog/592924 [2019_Python_]: https://my.oschina.net/u/2663968/blog/3061697 [hot3.png]: /images/20220113/e399dc16066b4703abe8ae5eca893336.png [30182923_8tlu.jpg]: /images/20220113/abfc1d7af5b345a4ad6cb4d924aeba0a.png [30182923_hTDy.jpg]: /images/20220113/7931fba1df354c4ca1b9e7bc486a78f9.png
还没有评论,来说两句吧...