(转)编码规范系列（一）：Eclipse Code Templates设置

背景：长久以来，对java编程中的注释不甚理解。再次学习《疯狂JAVA讲义》基础，深深的感到自己基本功的不牢固。所以要做到事无巨细，好好修炼。

认识注释

常识

注释的作用：

• 回顾原有的代码，快速理解原有的编程思路，提高效率，节省人生时间。
• 可读性第一，效率第二。提升与团队的写作能力。
• 代码即文档，使源代码更加的规范。

注释的分类：

• 单行注释
• 多行注释
• 文档注释

如果编写java源代码时添加了合适的文档注释，然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。

 eclipse中规范注释（一劳永逸）

Comments:

Comments-->Files（Java文件注释）
Comments-->Types（Java类注释）
Comments-->Fields（类字段注释）
Comments-->Constructors（构造函数注释）
Comments-->Methods（Java方法注释）
Comments-->Overriding methods（重写方法注释）
Comments-->Delegate methods（代理方法注释）
Comments-->Getters（Java Getter方法注释）
Comments-->Setters（Java Setters方法注释）

 

Code:

Code-->New Java files（新建java文件代码模板）
Code-->Method body（方法体模板）
Code-->Constructor body（构造函数模板）
Code-->Getter body（字段Getter方法模板）
Code-->Setter body（字段Setter方法模板）
Code-->Catch block body（异常catch代码块模板）

 

 

Comment和Code的区别在于——？？？？

注意：按照下述方法，导入codetemplates.xml文件后，在eclipse中需要进行注释的地方，鼠标点击要设置注释的元素（非元素外），按快捷键 ALT+SHIFT+J，即可添加模板中设置的注释。

ps：下文属于转载，链接 编码规范系列（一）：Eclipse Code Templates设置

另一篇文章与此相似，可以作为参考 Eclipse 注释模板设置

从工作开始，经历了几个项目的开发，现在的项目一般都是一个团队共同开发，而每个人都有自己的编码习惯，为了统一格式，项目组在项目开发之前都会制定一系列的规范。俗话说约定优于配置，但是在执行过程中往往发现效果不是很好（主要是指编码规范这一方面）。所以我们不得不采取一些措施来协助我们统一项目开发人员的编码风格。主要包括三个方面：设置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}, chenzhou1025@126.com 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}, chenzhou1025@126.com 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内容如下：

ps：可以根据自己的需要，对下述模板进行修改。

<?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}, chenzhou1025@126.com 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}, chenzhou1025@126.com 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就可以方便地生成我们自定义的注释，开发人员也容易接受！

 在新建一个java文件时候，就能看到如下的注释，其中main方法上的注释通过快捷键添加。

 

ps：上图有很多的tudo标签，一直以来不甚理解，细究之下，发现这个标签十分的有用。

具体使用方法查看另一篇博文：

在Eclipse中用TODO标签管理任务(Task)

自定义注释模板下载地址：

http://pan.baidu.com/s/1mhI2eEW

 命名和格式规范

命名规范

1) 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。单词太长也没关系，重要的是让人理解

 

2) 类名使用UpperCamelCase风格，必须遵从驼峰形式。

 

3) 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式。

 

4) 常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。

 

5) 抽象类命名使用Abstract或Base开头；异常类命名使用Exception结尾；测试类命名以它要测试的类的名称开始，以Test结尾。

 

6) 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。（此规则参考Spring框架结构）

正例：com.szfesc.clear.util、类名为StringUtils

 

7) 接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的Javadoc注释。

 

8) 对于Service和DAO类，基于SOA的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别。

 

9) Service/DAO层方法命名规约

l 获取单个对象的方法用get做前缀。

l 获取多个对象的方法用list做前缀。

l 获取统计值的方法用count做前缀。

l 插入的方法用save（推荐）或insert做前缀。

l 删除的方法用remove（推荐）或delete做前缀。

l 修改的方法用update做前缀。

 

10) long或者Long初始赋值时，必须使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。

 

格式规范

1) 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：

l 左大括号前不换行。

l 左大括号后换行。

l 右大括号前换行。

l 右大括号后还有else等代码则不换行；表示终止的右大括号后必须换行。

 

2) 左小括号和右边相邻字符之间不出现空格；同样，右小括号和左边相邻字符之间也不出现空格。

 

3) if/for/while/switch/do等保留字与小括号之间都必须加空格。

 

4) 任何运算符左右必须加一个空格。

 

5) 方法参数在定义和传入时，多个参数逗号后边必须加空格。

代码格式和模板设置

ps：最近公司在开发新的项目，为了规范开发过程，辉哥要求大家在IDE中进行下面三方面的配置

前言

在开发Java项目中为统一不同开发人员的代码风格，请按照如下步骤配置开发工具。以下配置默认开发工具为Eclipse，使用Intellij Idea的配置方式类似。

下载链接：

https://pan.baidu.com/s/1mhI2eEW 

在辉哥模板文件夹下有如下两个文件

代码格式文件--Formatter.xml

代码模板文件--Templates.xml

配置代码格式

eclipse 点击右键 source->Format或者Ctrl+Shift+f  可以格式化当前代码,这个格式化的规则当然也是可以设置的，

在window->preferences->Java->Code Style->Formatter 这里设置

下拉框中显示的是当前使用的格式化规则，点击Edit可以对当前文件进行编辑，

里面有各种设置缩进、大括号的换行、空格、空白行、控制语句的换行、注释等。

也可以，点击Import,导入已有模板。

从上面的下载链接下载代码格式文件Formatter.xml，导入到Eclipse中，并保存。

配置Save actions

设置好格式化模板之后，若果向每次保存之后即格式化，可以在Java->Editors->Save Actions中设置

启用Format source code 并且选择格式化全部还是 格式化 编辑过的行。

配置代码模板

下载代码模板配置文件Templates.xml，导入到Eclipse中，并保存：

preferences——Code Style——Code Template——Import 导入即可。 

至此，配置结束。