Java代码检查规范指导书x

1、 Java 代码检查规范指导书 审 核 : 日 期 : 批 准 : 日 期 : 实施日期 2010 年 05 月 24 日 版 本 号 A-0 密 级 内部 修改履历 日期 作者 修订要点 A-0 2010-5-24 吴兆彬 新作成 目录引言 . 5 2 应用范围 . 5 3 角色职责 . 5输入 . 5 5 输出 . 6 6 作业流程 . 6 6.1 C HECK S TYLE 安装与使用 . 7 6.1.1 CheckStyle 插件安装 . 7 “在线更新”安装方式 . 7 “手动下载”安装方式 . 7 6.1.2 CheckStyle 的配置与使用 .

2、9 导入：规则文件 . 9 启用：项目检查 . 10 查看：结果视图 . 10 6.2 E CLIPSE CODE S TYLE 的配置 . 10 “代码模版”的配置 . 10 “代码格式化”的配置 . 11 “代码清理”的配置 . 11 6.3代码修正 . 11 7 问题反馈（ FAQ ） . 1) 为什么第一句话需要以标点符号结束？. 2) “” 应该”在同一行”的提示信息？. 3) “一个局部常数，最好定义为全局常数”的提示信息？. 4) “条件逻辑语句应该被移除”的提示信息？. 5) “变量

3、应该声明为 PRIVATE ”的提示信息？ . 13 6) “工具类不应该存在 PRIVATE 或者默认构造函数”的提示信息？ . 14 7) “参数超过 7 个”的提示信息？ . 14 8) “类级的常量必须与模式 ”A-ZA-Z0-9*(_A-Z0- 9+)*$ ”相匹配” 的提示信息？ 14 9) “避免在语句中出现嵌套的赋值语句”的提示信息？. 15 1 引言 在编码规范推进过程中，陆续收到很多开发人员提交上来的疑问，这里逐一 统一做了一个整理和收集， 做成能够为开发人员提供指导意见的工作流程， 以提供大家互相参考和借鉴， 共通把电信信息化部的编码风格做到一致， 为编码质量的提高奠定基

4、础。 收集上来的问题，主要包括：在插件安装上的困难；在 CheckStyle 提示信息上的疑问点；使用 Eclipse Code Style 中的自动修复功能的问题；期望实现的改进建议； 2 应用范围 本指导书适用于编码阶段，可以进行代码的自查和修订，也可以适用于代码走查阶段。在纠正代码规范性的基础上， 更利于开发人员从业务层面进行走查的效果。 3 角色职责 角色 开发人员 走查人员 /QA 职责 对代码进行自查，以及代码的修正； 对代码进行规范性检查； 4 输入 1) Java 代码检查规范； 2) Eclipse Code Style 设置； 3) 代码检查配置文件；（2010 年大部检查

5、标准 _CheckStyle.xml ） 4) 代码修复工具；（2010 年大部检查标准 _template.xml 、2010 年大部 检查标准 _formatter .xml 、2010 年大部检查标准 _Clean Up.xml ） 5) 开发人员的代码； 5 输出1) 检查结果报表（图、表）2) 代码走查情况； 6 作业流程 1) 检查人员在开发环境（ Eclipse ）中进行插件的安装，可以选择手动下载安装方式，也可以选择在线更新方式； 2) 安装完 CheckStyle 之后，需要进行 CheckStyle 的配置；这里请选择 导入规则配置文件 2010 年大部检查标准 _Chec

6、kStyle.xml ； 3) 在项目工程上，设置激活 CheckStyle 检查4) 激活并编译项目工程后，打开 CheckStyle 检查结果视图，来查看检查结果5) 检查人员将检查报告发送给开发人员，由开发人员进行修复； 6) 开发人员导入修复规则： “代码模板配置文件” 2010 年大部检查标准 _template.xml 、“代码格式化配置文件” 2010 年大部检查标准 _formatter .xml 和“代码清理配置文件” 2010 年大部检查标准 _Clean Up.xml 。 7) 开发人员执行 CleanUp 操作，完成自动修复代码操作； 8) 对于无法自动化修复的代码，开

7、发人员进行手动修复； 6.1 CheckStyle 安装与使用 6.1.1 CheckStyle插件安装 根据大家的使用习惯，可以选择“在线更新”或者“手动下载”方式，进行 CheckStyle 的插件安装。 “在线更新”安装方式 1. Eclipse 3.4 以上版本的安装方式步骤 1、在 Eclipse 中，点 击“ Help”菜单； 2、点击“ Add.”按 钮，在弹出框中输入 输入相关信息； 3、选择合适的版本进 行安装 4、安装完成后，重新 启动 Eclipse； Eclipse3.4 Eclipse3.5 选 择 “ Software 选 择 “ Install N

8、ew Updates.” Software.” 输 入 ： “ Name ” 设 置 为 ： http:/eclipse-cs.sf.ne eclipse-cs； t/update/； “ Location ” 设 置 为 ： /upda te/； 选 择 “ Eclipse Checkstyle Plug-in 01002232103” 2. Eclipse 3.3 以下版本的安装方式步骤 1、在 Eclipse 中，点击“ Help”菜 单； 2、新建一个 “New Remote Site.” 3、选择合适的版本进行安装 4、安装

9、完成后，重新启动 Eclipse； 说明 选 择 “ Software Updates - Find and Install” 选择“ Search for new features” 输入名称“ eclipse-cs” 输 入 URL 地 址 “/update/” “手动下载”安装方式 1. 方式一： （如果是低版本的 Eclipse ，请将 dropins 修改为 links 目录） 步骤 1、访问 URL 地址进行下载； 2、解压安装包 3、整理安装文件 说明 下 载 地 址 ： /p

10、roject/showfiles.ph p?group_id=80344&package_id=107587 解 压 目 录 ： $Eclipse 安 装 目 录 /dropins/eclipse-cs/eclipse 将 “ $Eclipse 安 装 目 录 /dropins/eclipse-cs/eclipse”目录下的“site.xml”文件删除 将 “ $Eclipse 安 装 目 录 /dropins/eclipse-cs/eclipse/features”目录下的 jar 文件解压缩到所在目录的子文件夹中： “ net.sf.eclipsecs.migration_5. 1.0.2

11、01002232103.jar ”文件， 解 压 缩 到 “ net.sf.eclipsecs.migration_5. 1.0.201002232103 ”目录 “ net.sf.eclipsecs_0100 2232103.jar ” 文 件， 解压 缩到 “ net.sf.eclipsecs_0100 2232103 ”目录 4、重启 Eclipse 2. 方式二： （如果是低版本的 Eclipse 步骤 1、访问 URL 地址进行下载； 2、解压安装包 ，请将 dropins 替换为 links 目录；） 说明 下 载 地 址 ： http:/sourcef

12、/project/showfiles.ph p?group_id=80344&package_id=107587 在任意路径下，新建一个“ eclipse-cs” 目录，并在其下新增“ eclipse”目录，将安装包解压缩到的该目录 3、整理安装文件 将该目录的“ site.xml”文件删除 将该目录的“ features”子目录中的 jar 文件，解压缩到所在目录的子文件夹中： “ net.sf.eclipsecs.migration_5. 1.0.201002232103.jar ”文件， 解 压 缩 到 “ net.sf.eclipsecs.migration_5. 1.

13、0.201002232103 ”目录 “ net.sf.eclipsecs_0100 2232103.jar ” 文 件， 解压 缩到 “ net.sf.eclipsecs_0100 2232103 ”目录 4、添加链接文件 5、重启 Eclipse 6.1.2 CheckStyle的配置与使用 导入：规则文件 步骤 1、在 Eclipse 中，点击“ Window ” 在“ $Eclipse 安装目录 /dropins ”目录下 ， 新 建 一 个 文 本 文 件 ， 命 名 为 “ eclipse-cs.link”，在文件中添加以下内容： pat

14、h=新建的“ eclipse-cs”目录全路径（如： F:/eclipse/plugins/eclipse-cs） 说明 菜单，选择“ Preferences” 2、新建配置 3、设置默认 选择“CheckStyle”配置项，点击“ New.” 按钮； 在“Name”中，输入“ 2010 年大部检查标准”； 点击“ Import”按钮，选择“ 2010 年大部检查标准（ Java）.xml ”文件； 点击“ OK ”完成； 选中导入的“ 2010 年大部检查标准”规则项，点击“ Set as Default”按钮，将该 启用：项目检查 步骤 1、选中打开的项目名称，点击右 键；

15、 2、启用 /禁用 CheckStyle； 配置设置为默认规则； 说明 启用：在右键菜单中， 点击“Checkstyle”菜单的“ Activate Checkstyle”项，则该项目已经启动 CheckStyle 规则； 禁用：在右键菜单中， 点击“Checkstyle”菜单的“ Deactivate Checkstyle”项，则该项目已经禁用 CheckStyle 规则； 查看：结果视图 步骤 1、点击“ Window ”菜单，选择 “ Show View - Others.”； 2、打开三个 CheckStyle 视图，可 以看到相应的检查结果； 6.2 Eclipse

16、Code Style 的配置 “代码模版”的配置 步骤 1、在 Eclipse 中，点击“ Window ” 菜单，选择“ Preferences” 2、导入模版配置文件 说明 在“CheckStyle”目录下，有三个可选视 图 Checkstyle Violations Checkstyle Violations Chart Duplicated Code 说明 选择“ JavaCode StyleCode Templates” 项； 点击“ Import.”按钮，选择“ 2010 年大 3、设置默认 “代码格式化”的配置 步骤 1、在 Eclipse 中，点

17、击“ Window ” 菜单，选择“ Preferences” 2、导入格式化配置文件 3、设置默认 “代码清理”的配置 步骤 1、在 Eclipse 中，点击“ Window ” 菜单，选择“ Preferences” 2、导入格式化配置文件 3、设置默认 6.3 代码修正 部检查标准 _template.xml”文件； 点击“ Apply ”按钮，则设置该模版配置为默认配置； 说明 选择“ JavaCode StyleFormatter”项；点击“ Import.”按钮，选择“ 2010 年大部检查标准 _formatter.xml”文件； 点击“ Apply ”按钮，则设

18、置该格式化配置为默认配置； 说明 选择“ JavaCode StyleClean Up”项；点击“ Import.”按钮，选择“ 2010 年大部检查标准 _Clean Up.xml”文件； 点击“ Apply ”按钮，则设置该清理配置为默认配置； 1. “代码模版配置”，适用于自动生成“注释”和“代码”时，套用的模版； 2. “代码格式化配置” ，适用于配合“ Ctrl + Shift + f ”键来使用，完成代码的自动格式化；（建议在代码提交之前，先执行代码格式化） 3. “代码清理配置”配合“ Source 菜单的 Clean Up ”功能来使用，完成代码的自动清理；（建议在代码提交之前

19、，先执行代码清理） 4. 手动修复，针对个别无法自动化修正的操作，需要开发人员手动进行修正； 7 问题反馈 1（Faq） 1) 为什么第一句话需要以标点符号结束？ 错误写法 正确写法/* /* * 密码 * 密码*/ */ private Textbox password; private Textbox password; 注释的第一句，确保以正确的标点符号结束，可以是中文 / 英文输入法的句号、问号或叹号；因为自动生成的 JavaDoc API 文档中，会自动将第一句话放在类注释文档的方法大纲表格和索引信息中；如果没有合适的 标点符号 ，会让生 成 的类注释 文档的格 式变形；对 于使用有

20、 “inheritDoc ”的注释，可以不使用标点符号，因为该标签表示引用了接口的文档注释。 2) “” ”应该在同一行”的提示信息？ 错误写法 正确写法if (condition) if (condition) System. out .print( . ); System. out .print( . ); else else System. out .print( . ); System. out .print( . ); 提示信息中的“同一行”指的是“大括号”与后面的“ else 语句”应该放在同一行。因为在 Sun 的 Java 规范和 Eclipse 的内置 Java 规范都是采用

21、同行的书写方式。 3) “一个局部常数，最好定义为全局常数”的提示信息？ 错误写法 正确写法 (i = 3) 先声. public static final int ITERATOR_THREE = 3; 然后，在方法中使用： if (i = ITERATOR_THREE) . 这么做避免出现 Magic Number ，修正以后，数值获得正确的含义，更能表达数值的用途，也更利于提高代码的可读性。 4) “条件逻辑语句应该被移除”的提示信息？ 错误写法 正确写法 if (userPermission = null ) return (userPermission != null ); retu

22、rn false ; else return true ; 减少不必要的 boolean 表达式的逻辑判断，使代码更加简洁，也减少代码行数和阅读量。 5) “变量应该声明为 private ”的提示信息？ 错误写法 正确写法 public static private static PageBase pageBase ; PageBase pageBase ; /* * return pageBase 属性 */ public static PageBase getPageBase() return pageBase /* * param pageBase 设置 pageBase 属性 */

23、public static void setPageBase(PageBase pageBase) SubTest. pageBase = pageBase; 这个属于类设计规则问题，默认情况下，只允许 static final 属性是 public 的，其他的属性必须是 private 的；当然，也可以根据需要设置 为包级可见，或者子类可见，或者允许某些成员属性作为特例。这么做的好处在于，能够保证类的封装性，对外访问的安全性，也更易于代码的维护。 6) “工具类不应该存在 public 或者默认构造函数”的提示信息？ 错误写法 正确写法 public class StringUtils pu

24、blic class StringUtils / 没有声明构造函数，或者声明了 private StringUtils() public 的构造函数 . . 这属于类的设计规则问题。对于工具类来说，所有的成员都是静态的，不必要实例化；但是，对于调用者来说，有可能去实例化该工具类，这样就造成了不必要的初始化对象实例，也就导致内存浪费。 7) “参数超过 7 个”的提示信息？ 错误写法 正确写法 public static String public static String windowsalertRedirectBack(String windowsalertRedirectBack(Str

25、imsg, msg,HttpServletRequest request, String dvtype, String HttpServletRequest request, Po po) ? ? String roomid, String roomname, String rmwidth, String rmheight) ? ? 这属于大小规则问题。将这么多参数，封装成一个或者多个对象，然后将这个或几个对象作为方法输入。这么做既简洁，而且调用者也不容易出错。 8) “类级的常量必须与模式 ” A-ZA-Z0-9*(_A-Z0-9+)*$ 相匹配”的提示信息？ ” 错误写法 正确写法 pri

26、vate static final int dayArray = new int 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 ; private static final int DAY_ARRAY = new int 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 ; 这属于命名规范问题。对于常量名必须全部使用大写字母，不同单词间 使用下划线分隔。 9) “避免在语句中出现嵌套的赋值语句”的提示信息？ 错误写法 正确写法 for ( int i = 0; (i = s.indexOf(s1) =

27、0;) arrayList.add(s.substring(0, i); s = s.substring(i + 1, s.length(); for ( int i = s.indexOf(s1); i = 0; i = s.indexOf(s1) arrayList.add(s.substring(0, i); s = s.substring(i + 1, s.length(); 将赋值语句置于嵌套语句之中， 如上面例子中的 “(i = s.indexOf(s1) = 0; ”语句中嵌套了“ i = s.indexOf(s1) ”赋值语句；这么做，往往加 大代码阅读的难度，也不易于维护，因此，尽量不要出现嵌套在其他语句中的赋值语句。 8 问题反馈 2（Faq）10) “类应该被声明为 final ”的提示信息？ 问题描述 public class BaseCommonConstant private BaseCommonConstant() 该类作为工具类的基类， 允许子类继承， 但是却提示声明为 final ，这样子类就没