• 欢迎访问 winrains 的个人网站!
  • 本网站主要从互联网整理和收集了与Java、网络安全、Linux等技术相关的文章,供学习和研究使用。如有侵权,请留言告知,谢谢!

Java 编码规范

Java技术 winrains 7个月前 (02-13) 54次浏览

1 引言

1.1 编写目的

本规范是参考公司的《XXXX Java开发技术规范》、谷歌公司的《Google Java Style Guide》以及阿里巴巴集团和《Java开发手册》编制而成,用于约束公司Java项目的开发。

1.2 范围

本规范规定了使用Java语言编程时的排版、注释、命名、编码等所需要遵守的规则。

本规范适用于使用Java语言编程的产品和项目,本公司所有Java项目的编码必须符合本规范的规定。

2 Java编码规范

2.1 源文件

  • 源文件以其最顶层的类名来命名,大小写敏感,文件扩展名为.java。
  • 源文件编码格式为UTF-8。
  • 源文件结构由以下四部分组成:
  • 版权信息
  • package语句
  • import语句
  • 一个顶级类(只有一个)

以上每个部分之间用一个空行隔开。

  • 版权信息位于Java源文件的开头,各源文件的版权信息除年份外,格式需保持统一。例:
/*
 * Copyright (C) 2019 XXXX network Co. Ltd.
 * All right reserved.
 */

2.2 命名风格

  • 代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。
  • 代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用拼音的方式。
  • 类名使用UpperCamelCase风格,类名通常是名词或名词短语。
  • 包名全部小写,连续的单词只是简单地连接起来,不使用下划线。包名统一使用单数形式,但是类名如果有复数含义,类名可以使用复数形式。例:

应用工具类包名为com.xxxx.util、类名为MessageUtils

  • 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格,必须遵从驼峰形式。方法名通常是动词或动词短语。参数应该避免用单个字符命名。局部变量要避免用单字符进行命名,除了临时变量和循环变量。
  • 常量名命名模式为CONSTANT_CASE,全部字母大写,用下划线分隔单词。每个常量都是一个静态final字段,通常是名词或名词短语。
  • 系统内所有常量应统一位于Constant常量类中,不应分散位于各个不同类中,不便于统一维护和管理。
  • long或者Long赋值时,数值后使用大写的L,不能是小写的l,小写容易跟数字1混淆,造成误解。
  • 抽象类命名使用AbstractBase开头;异常类命名使用Exception结尾;测试类命名以它要测试的类的名称开始,以Test结尾。
  • 中括号是类型的一部分,应定义成String[] args,而不是String args[]
  • 避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名,使可读性降低。
  • 如果模块、接口、类、方法使用了设计模式,在命名时需体现出具体模式。例:
public class OrderFactory;
public class ResourceObserver;
  • 对于ServiceDAO类,内部的实现类用Impl的后缀与接口区别。例:

CacheServiceImpl实现CacheService接口。

  • 如果是形容能力的接口名称,取对应的形容词为接口名(通常是–able的形容词)。例:

AbstractTranslator实现Translatable接口。

  • 枚举类名带上Enum后缀,枚举成员名称需要全大写,单词间用下划线隔开。
  • Service/DAO层方法命名要求如下:
  • 获取单个对象的方法用get做前缀。
  • 获取多个对象的方法用list做前缀,复数形式结尾如:listObjects
  • 获取统计值的方法用count做前缀。
  • 插入的方法用save/insert做前缀。
  • 删除的方法用remove/delete做前缀。
  • 修改的方法用update做前缀。

2.3 代码格式

2.3.1 大括号

  • 大括号与if, else, for, do, while语句一起使用,即使只有一条语句(或是空),也应该把大括号写上。例:
if (flag) {
    return true;
}
  • 如果是大括号内代码为空,则简洁地写成{}即可,大括号中间无需换行和空格。例:
void doNothing() {}
  • 如果大括号内代码不为空,则需要满足以下要求:
  • 左大括号前不换行。
  • 左大括号后换行。
  • 右大括号前换行。
  • 右大括号后还有else等代码则不换行;表示终止的右大括号后必须换行。

2.3.2 空行

  • 每个语句后要换行。
  • 类内连续的成员之间应增加空行,包括字段,构造函数,方法,嵌套类,静态初始化块,实例初始化块。
  • 两个连续字段之间的空行是可选的,用于字段的空行主要用来对字段进行逻辑分组。
  • 在函数体内,语句的逻辑分组间使用空行。
  • 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。任何情况下,不应插入多个空行进行分隔。

2.3.3 空格

  • 在以下位置应输入单个空格:
  • 分隔任何保留字与紧随其后的左括号(()之间(如if, for,wh ile, switch, catch等)。
  • 分隔任何保留字与其前面的右大括号(})(如else, catch)。
  • 在任何左大括号前({)。
  • 在任何二元或三元运算符的两侧。
  • 在, : ;及右括号())后。
  • 如果在一条语句后做注释,则双斜杠(//)两边都要空格。
  • 类型和变量之间。
  • 方法参数在定义和传入时,多个参数逗号后边必须加空格。
  • 左小括号和字符之间不出现空格;同样,右小括号和字符之间也不出现空格。
  • 采用4个空格缩进,禁止使用tab字符。如果使用tab缩进,必须设置1个tab为4个空格。
  • 注释的双斜线与注释内容之间有且仅有一个空格。例:
// 这是示例注释,请注意在双斜线之后有一个空格
String param = new String();
  • 在进行类型强制转换时,右括号与强制转换值之间不需要任何空格隔开。例:
long first = 1000000000000L;
int second = (int)first + 2;

2.4 注释

  • 类、类属性、类方法的注释必须使用Javadoc规范,使用/**内容*/格式,不得使用// xxx方式。
  • 所有的抽象方法(包括接口中的方法)必须要用Javadoc注释、除了返回值、参数、异常说明外,还必须指出该方法做什么事情,实现什么功能。
  • 所有的类都必须添加创建者和创建日期。
  • 方法内部单行注释,在被注释语句上方另起一行,使用//注释。
  • 所有的枚举类型字段必须要有注释,说明每个数据项的用途。
  • 代码修改的同时,注释也要进行相应的修改,尤其是参数、返回值、异常、核心逻辑等的修改。

2.5 异常处理

  • 一般情况下,需要对捕获的异常进行响应,如果它确实是不需要在catch块中做任何响应,需要做注释加以说明。
  • Java类库中定义的可以通过预检查方式规避的RuntimeException异常不应该通过catch的方式来处理,比如:NullPointerExceptionIndexOutOfBoundsException等等。
  • catch时请分清稳定代码和非稳定代码,稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型,再做对应的异常处理。不应对大段代码进行try-catch,使程序无法根据不同的异常做出正确的应激反应,也不利于定位问题。
  • 捕获异常是为了处理它,不要捕获了却什么都不处理而抛弃之,如果不想处理它,
    请将该异常抛给它的调用者。最外层的业务使用者,必须处理异常,将其转化为用户可以理解的内容。
  • try块放到了事务代码中,catch异常后,如果需要回滚事务,一定要注意手动回滚事务。
  • finally块必须对资源对象、流对象进行关闭,有异常也要做try-catch
  • 不要在finally块中使用returntry块中的return语句执行成功后,并不马上返回,而是继续执行finally块中的语句,如果此处存在return语句,则在此直接返回,直接丢弃掉try块中的返回点。

2.6 其它

  • 每次只声明一个变量,不要使用组合声明,例如,不能采用如此方式:int a, b;
  • 不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法),而是在第一次需要使用它时才声明。局部变量在声明时最好就进行初始化,或者声明后尽快进行初始化。
  • 单行字符数限制不超过120个,超出需要换行,换行时遵循如下原则:
  • 第二行相对第一行缩进4个空格,从第三行开始,不再继续缩进,参考示例。
  • 运算符与下文一起换行。
  • 方法调用的点符号与下文一起换行。
  • 方法调用中的多个参数需要换行时,在逗号后进行。
  • 在括号前不要换行。
  • IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式,
    要使用Windows格式。
  • 避免通过一个类的对象引用访问此类的静态变量或静态方法,直接用类名来访问即可。
  • 不能使用过时的类或方法。
  • 当一个类有多个构造方法,或者多个同名方法,这些方法应该按顺序放置在一起,便于阅读。
  • 类内方法定义的顺序依次是:公有方法或保护方法 > 私有方法 > getter/setter方法。
  • 在一个switch块内,每个case要么通过continue/break/return等来终止,要么注释说明程序将继续执行到哪一个case为止;在一个switch块内,都必须包含一个default语句并且放在最后,即使它什么代码也没有。

3 MySQL规范

  • 表名、字段名必须使用小写字母或数字,禁止出现数字开头,禁止两个下划线中间只出现数字。
  • MySQL在Windows下不区分大小写,但在Linux下默认是区分大小写。因此,数据库名、表名、字段名,都不允许出现任何大写字母,避免节外生枝。
  • 表名不使用复数名词。表名应该仅仅表示表里面的实体内容,不应该表示实体数量,对应于DO类名也是单数形式,符合表达习惯。
  • 禁用MySQL保留字作为表名和字段名。
  • 主键索引名为pk_字段名;唯一索引名为uk_字段名;普通索引名则为idx_字段名。pk_primary keyuk_unique keyidx_index的简称。
  • 表必备三字段:idcreate_timeupdate_time。其中id必为主键,类型为bigint unsigned、单表时自增、步长为1。create_timeupdate_time的类型均为datetime类型。
  • 库名与应用名称尽量一致。
  • 如果修改字段含义或对字段表示的状态追加时,需要及时更新字段注释。
  • 页面搜索严禁左模糊或者全模糊,索引文件具有B-Tree的最左前缀匹配特性,如果左边的值未确定,那么无法使用此索引。
  • 建组合索引的时候,区分度最高的在最左边。
  • 在表查询中,一律不要使用*作为查询的字段列表,需要哪些字段必须明确写明。

版权声明:文末如注明作者和来源,则表示本文系转载,版权为原作者所有 | 本文如有侵权,请及时联系,承诺在收到消息后第一时间删除 | 如转载本文,请注明原文链接。
喜欢 (1)