編碼規范系列（一）：Eclipse Code Templates設置

從工作開始，經歷了幾個項目的開發，現在的項目一般都是一個團隊共同開發，而每個人都有自己的編碼習慣，為了統一格式，項目組在項目開發之前都會制定一系列的規范。俗話說約定優於配置，但是在執行過程中往往發現效果不是很好（主要是指編碼規范這一方面）。所以我們不得不采取一些措施來協助我們統一項目開發人員的編碼風格。主要包括三個方面：設置Code Templates、Eclipse formatter、Checkstyle，本篇主要介紹如何設置Code Templates，具體步驟如下：

 

打開Window->Preferences->Java->Code Style->Code Templates

點擊"Import"，導入模板codetemplates.xml文件。

codetemplates.xml內容是我們自己預先定義好的，在這里先不詳細描述，我們可以看到Eclipse Code Templates界面中間Configure generated code and comments區域包含了兩個菜單樹：Comment、Code，如下圖所示：

Comments代表注釋模板，Code代表代碼模板，其中每一個子菜單代表子項的模板。

我們只要點擊某一個子項，就會在界面下方的Pattern區域看到該項我們所定義的模板內容和格式，如下圖所示：

如上圖所示，當我們點擊Comments下的Files子菜單時，下面的Pattern會顯示Java文件的頭部注釋。

下面詳細列出每一個子項的模板格式：

Comments-->Files（Java文件注釋）

/**
 * Project Name:${project_name}
 * File Name:${file_name}
 * Package Name:${package_name}
 * Date:${date}${time}
 * Copyright (c) ${year}, [e-mail] All Rights Reserved.
 *
 */

Comments-->Types（Java類注釋）

/**
 * ClassName: ${type_name} <br/>
 * Function: ${todo} ADD FUNCTION. <br/>
 * Reason: ${todo} ADD REASON(可選). <br/>
 * date: ${date} ${time} <br/>
 *
 * @author ${user}
 * @version ${enclosing_type}${tags}
 * @since JDK 1.6
 */

Comments-->Fields（類字段注釋）

/**
 * ${field}:${todo}(用一句話描述這個變量表示什么).
 * @since JDK 1.6
 */

Comments-->Constructors（構造函數注釋）

/**
 * Creates a new instance of ${enclosing_type}.
 *
 * ${tags}
 */

Comments-->Methods（Java方法注釋）

/**
 * ${enclosing_method}:(這里用一句話描述這個方法的作用). <br/>
 * ${todo}(這里描述這個方法適用條件 – 可選).<br/>
 * ${todo}(這里描述這個方法的執行流程 – 可選).<br/>
 * ${todo}(這里描述這個方法的使用方法 – 可選).<br/>
 * ${todo}(這里描述這個方法的注意事項 – 可選).<br/>
 *
 * @author ${user}
 * ${tags}
 * @since JDK 1.6
 */

Comments-->Overriding methods（重寫方法注釋）

/**
 * ${todo} 簡單描述該方法的實現功能（可選）.
 * ${see_to_overridden}
 */

Comments-->Delegate methods（代理方法注釋）

/**
 * ${tags}
 * ${see_to_target}
 */

Comments-->Getters（Java Getter方法注釋）

/**
 * ${bare_field_name}.
 *
 * @return  the ${bare_field_name}
 * @since   JDK 1.6
 */

Comments-->Setters（Java Setters方法注釋）

/**
 * ${param}.
 *
 * @param   ${param}    the ${bare_field_name} to set
 * @since   JDK 1.6
 */

Code-->New Java files（新建java文件代碼模板）  

/**
 * Project Name:${project_name}
 * File Name:${file_name}
 * Package Name:${package_name}
 * Date:${date}${time}
 * Copyright (c) ${year}, [e-mail] All Rights Reserved.
 *
*/
${filecomment}

${package_declaration}
/**
 * ClassName:${type_name} <br/>
 * Function: ${todo} ADD FUNCTION. <br/>
 * Reason:   ${todo} ADD REASON. <br/>
 * Date:     ${date} ${time} <br/>
 * @author   ${user}
 * @version
 * @since    JDK 1.6
 * @see
 */
${typecomment}
${type_declaration}

Code-->Method body（方法體模板）

// ${todo} Auto-generated method stub
${body_statement}

Code-->Constructor body（構造函數模板）

${body_statement}
// ${todo} Auto-generated constructor stub

Code-->Getter body（字段Getter方法模板）

return ${field};

Code-->Setter body（字段Setter方法模板）

${field} = ${param};

Code-->Catch block body（異常catch代碼塊模板）  

// ${todo} Auto-generated catch block
${exception_var}.printStackTrace();

 

其中codetemplates.xml內容如下：

<?xml version="1.0" encoding="UTF-8" standalone="no"?><templates><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   JDK 1.6
 */</template><template autoinsert="false" context="settercomment_context" deleted="false" description="Comment for setter method" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.settercomment" name="settercomment">/**
 * ${param}.
 *
 * @param   ${param}    the ${bare_field_name} to set
 * @since   JDK 1.6
 */</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">/**
 * Creates a new instance of ${enclosing_type}.
 *
 * ${tags}
 */
</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">/**
 * Project Name:${project_name}
 * File Name:${file_name}
 * Package Name:${package_name}
 * Date:${date}${time}
 * Copyright (c) ${year}, [e-mail] All Rights Reserved.
 *
 */</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} &lt;br/&gt;
 * Function: ${todo} ADD FUNCTION. &lt;br/&gt;
 * Reason: ${todo} ADD REASON(可選). &lt;br/&gt;
 * date: ${date} ${time} &lt;br/&gt;
 *
 * @author ${user}
 * @version ${enclosing_type}${tags}
 * @since JDK 1.6
 */</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 JDK 1.6
 */</template><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">/**
 * ${enclosing_method}:(這里用一句話描述這個方法的作用). &lt;br/&gt;
 * ${todo}(這里描述這個方法適用條件 – 可選).&lt;br/&gt;
 * ${todo}(這里描述這個方法的執行流程 – 可選).&lt;br/&gt;
 * ${todo}(這里描述這個方法的使用方法 – 可選).&lt;br/&gt;
 * ${todo}(這里描述這個方法的注意事項 – 可選).&lt;br/&gt;
 *
 * @author ${user}
 * ${tags}
 * @since JDK 1.6
 */</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">/**
 * ${todo} 簡單描述該方法的實現功能（可選）.
 * ${see_to_overridden}
 */</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="newtype_context" deleted="false" description="Newly created files" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.newtype" name="newtype">/**
 * Project Name:${project_name}
 * File Name:${file_name}
 * Package Name:${package_name}
 * Date:${date}${time}
 * Copyright (c) ${year}, [e-mail] All Rights Reserved.
 *
*/
${filecomment}

${package_declaration}
/**
 * ClassName:${type_name} &lt;br/&gt;
 * Function: ${todo} ADD FUNCTION. &lt;br/&gt;
 * Reason:   ${todo} ADD REASON. &lt;br/&gt;
 * Date:     ${date} ${time} &lt;br/&gt;
 * @author   ${user}
 * @version
 * @since    JDK 1.6
 * @see
 */
${typecomment}
${type_declaration}
</template><template autoinsert="true" context="classbody_context" deleted="false" description="Code in new class type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.classbody" name="classbody">
</template><template autoinsert="true" context="interfacebody_context" deleted="false" description="Code in new interface type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.interfacebody" name="interfacebody">
</template><template autoinsert="true" context="enumbody_context" deleted="false" description="Code in new enum type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.enumbody" name="enumbody">
</template><template autoinsert="true" context="annotationbody_context" deleted="false" description="Code in new annotation type bodies" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.annotationbody" name="annotationbody">
</template><template autoinsert="true" context="catchblock_context" deleted="false" description="Code in new catch blocks" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.catchblock" name="catchblock">
// ${todo} Auto-generated catch block
${exception_var}.printStackTrace();
</template><template autoinsert="false" context="methodbody_context" deleted="false" description="Code in created method stubs" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.methodbody" name="methodbody">
// ${todo} Auto-generated method stub
${body_statement}</template><template autoinsert="true" context="constructorbody_context" deleted="false" description="Code in created constructor stubs" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.constructorbody" name="constructorbody">
${body_statement}
// ${todo} Auto-generated constructor stub
</template><template autoinsert="true" context="getterbody_context" deleted="false" description="Code in created getters" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.getterbody" name="getterbody">return ${field};</template><template autoinsert="true" context="setterbody_context" deleted="false" description="Code in created setters" enabled="true" id="org.eclipse.jdt.ui.text.codetemplates.setterbody" name="setterbody">${field} = ${param};</template></templates>

 

設置Code Templates的目的主要是為了統一各種注釋的格式以及代碼的模板，只要設定好Code Templates之后利用Eclipse就可以方便地生成我們自定義的注釋，開發人員也容易接受！