Java 编码规范
1. 简介
目的: 1.1 目的: 本文提供一整套编写高效可靠的 Java 代码的标准、约定和指南。它们以安全可靠的软件工程原则为基础,使代码 易于理解、维护和增强。而且,通过遵循这些程序设计标准,你作为一个 Java 软件开发者的生产效率会有显著提 高。经验证明,若从一开始就花时间编写高质量的代码,则在
软件开发阶段,对代码的修改要容易很多。最后,遵 循一套通用的程序
设计标准将带来更大的一致性,使软件开发团队的效率明显提高。 1.2 范围 本指南适用于使用 Java 编写的程序代码。
2. 代码组织与风格
代码的空间和易读性 易读性: 2.1 代码的空间和易读性: 在代码中因该合理地利用空间,区分开具有逻辑性地代码块,增强可读性;
2.1.1
代码空格使用:
在代码中,’,’ ‘;’等标点后应有一个空格;’+’ ‘-‘ ‘*’等运算符前后均应有一个空格;其他符号如’.’ ‘(‘ ’)’ 等原则上不须空格。
2.1.2 2.1.3
代码空行使用:
在代码中逻辑性代码块的起始、结尾处,都应该加入空行,并在起始处写注释。
嵌套和缩进: 2.2 嵌套和缩进: 在一个代码块中应该缩进,包括有:If/for/while 等语句; 在续行的代码中应缩进; 缩进取 4 格,使用 Tab 字符,Java 中 Tab 应取 4 格; 代码风格: 2.3 代码风格:
2.3.1
续行:
在代码编写中,程序代码每行不应太长,当一行代码超过打印页宽应续行; 2.3.1.1 函数调用续行: frame.setLocation((screenSize.width - frameSize.width) / 2, (screenSize.height - frameSize.height) / 2);
2.3.1.2 SQL 字串续行: SQL 语句中关键字使用全大写,如 SELECT、AND 等。
String sql = "SELECT Max(JYLSH) “ + ” FROM DHSB_SYRZB " + " WHERE SYDW = '" + Constants._Swjg_Bm.substring(0,6) + "'" + " AND RZLY = '1'" + " AND NSHBS = '" + nsrbm.substring(6) + "'" + " AND JYLB = '1'" + " AND CZBZ = '1'";
代码注释: 3. 代码注释:
注释要求: 3.1 注释要求: 无论是用户端表示层程序还是组件
程序,注释必不可少。 要求能占程序总量的 10%以上。 注释必须在程序改变时实时更新。 简单明了,确保任何程序员都可以读懂。 注释一般应写在代码之前,并与代码分开不同的行;但对于说明变量含义的注释,一般应写在变量说明的同 行的行末,并且在各行间保持对齐; 如果可能,尽量使用单行注释 ‘//’。 对于代码维护,应在过程或方法中记录相应修改的作者、时间,并在具体修改的位置用特殊的标签注明(标 签一般应包含修改人的名字汉语拼音或拼音简写、日期戳和可选的修改项目名字)。例子如下: //modify by zhw 2006-5-15 修改内容的文字说明 ... ... ... //modify by zhw 2006-5-15 end
注释方法: 3.2 注
释方法:
3.2.1 3.2.2 3.2.3
每个构件(.java 文件)的顶部应该有注释。 构件内的每个过程或方法应该有注释。 每个模块级变量、重要的变量必须给出注释,使用“//”单行注释。
包括:模块名称、功能描述、作者、版本
包括:功能描述、参数说明、返回值说明、最后更新作者(如果有改动)、最后更新日期(如果有改动)
辅助生成统一的注释: 3.3 使用
JavaDoc 辅助生成统一的注释: 为规范、 方便生成统一的程序
文档, 应在代码注释中遵循 JavaDoc 的注释规范 (建议在开发工具中输入 “/**回车” , 填入所有自动弹出项。)
3.3.1
构件约定注释与 JavaDoc 中对应:
See Todo Author Version
模块名称: 功能描述: 作者: 版本:
/** * 对系统规范化的异常处理。包含各种异常编码,标准出错提示与日志的产生和管理。 * * 异常类型 ID * 1-49 :
系统内部异常 - 标准处理:写日志,向客户端抛出 CustomException 异常 * 50-99 :用户界面异常 - 标准处理:写日志,向客户端抛出对应的自定义异常 * 100 以上:扩展异常 * * 注意:写日志时应使用 getSysMsg() 获得对应的异常日志记录串;向用户