Java基礎學習總結（36）——Java註釋模板

代碼註釋是對代碼設計者、代碼閱讀者以及系統間調用提供了有效的幫助，最大限度的提升團隊開發合做效率加強系統的可維護性。咱們追求簡化，不是爲了寫註釋而寫註釋。

（快速使用請直接看6、7、八）

1、原則：

1.註釋形式統一

使用統一的註釋風格，不要隨意建立新的註釋風格。

2.註釋準確簡潔

內容要簡單、明瞭，防止註釋的多義性，錯誤的註釋不但無益反而有害。

2、註釋條件：

1.基本註釋（必須加）

a)類（接口）的註釋

b)構造函數的註釋

c)方法的註釋

d)全局變量的註釋

e)字段/屬性的註釋

注:Bean對象的getter、setter方法不需加註釋。

2.局部註釋（必須加）

a)典型算法必須有註釋。

b)在代碼不明晰處必須有註釋。

c)在代碼修改處加上修改標識的註釋。

d)在循環和邏輯分支組成的代碼中加註釋。

e)爲他人提供的接口必須加詳細註釋。

3、註釋格式：

1.單行(single-line)註釋：「//……」

2.塊(block)註釋：「/*……*/」

3.文檔註釋：「/**……*/」

4、javadoc 註釋標籤語法

@author對類的說明標明開發該類模塊的做者

@version對類的說明標明該類模塊的版本

@see對類、屬性、方法的說明參考轉向，也就是相關主題

@param對方法的說明對方法中某參數的說明

@return對方法的說明對方法返回值的說明

@exception對方法的說明對方法可能拋出的異常進行說明

5、註釋：

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 );

}

}

......

｝

6、代碼修改註釋

註釋格式以下：

修改人，修改時間，UC編碼，迭代編碼修改說明（緣由、內容）能夠單行簡短註釋

如：

//jarek 2015年11月9日上午11:36:18 @UC_XXXX @In 變動說明（緣由、修改內容）

代碼改動量小時，在修改代碼行前追加註釋

對於改動量大時，能夠在方法前追加註釋

對整個java類變化大時，能夠從新追加類註釋

7、導入模版(模版文件見文檔附件)

<?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>

<?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>

8、使用：

只要導入在eclips中導入註釋模版便可

經過 /** +回車或 mc +alt+/ 會調出全部模版，提供方便快速註釋的功能。