1360 字
7 分钟
Java语言编程规范
规范刷新流程：提交评论/mr -> 规范组讨论 -> 达成一致 -> 修改/合入mr -> 发布评审 -> 发布正式版本
代码风格
命名
| 类别 | 命名风格 |
|---|---|
| 接口、类、注解、枚举类型 | 大驼峰，测试类加Test后缀，文件名为顶层类名.java |
| 类的属性、局部变量、方法、方法参数 | 小驼峰，测试方法可以有下划线 |
| 静态常量、枚举值 | 全大写，下划线分割_ |
| 泛型类型变量 | 单个大写字母，可借一个数字或者接下划线加若干个大写字母 |
| 异常 | 加后缀Exception或Error |
规范中的常量是指不可被修改的field和枚举常量。“不可被修改”需要同时满足以下两个条件：
- field的值/对象不可被修改为其他的值/对象
- field为对象类型时，对象在初始化完成后其属性不能被修改
常量定义的一般格式为[访问修饰符] static final 类型 常量名 = 常量值;
常量有一些注意事项：
- 常量的命名要尽量表达完整的语义。
- 避免使用魔鬼数字（难以理解的数字或字符串），要使用有意义的常量来代替。
- 不建议使用常量类集中管理所有的常量，推荐按功能进行管理，就近定义常量。
- mutable对象禁止定义为常量。
注释
注释使用的总体原则是：按需注释。
- 要从读者的角度触发，按需注释。
- 注释要简洁、明了、无歧义，信息全面但不冗余。
- 不要添加无效、重复的注释。
- 注释要与代码同步修改。
JavaDoc中有几个要求：
- 要对public、protected修饰的元素添加JavaDoc修饰。
- 顶层public类的JavaDoc应该包含功能说明和创建日期/版本信息。
- 方法的JavaDoc中应该包含功能说明，根据时机需要按顺序使用
@param, @return, @throws标签对参数、返回值、异常进行注释。 - 不要添加空有格式的方法头注释。
- 涉及线程安全时，要进行相关的说明。
代码注释的时候，
- 非首行代码的注释应该与前面的代码之间加一空行。
- 代码右侧的注释，代码、注释符、注释之间至少留一个空格。
- 正式交付的代码不应包含TODO/FIXME注释。
格式
在编码规范的指导下，审慎地编排代码以使代码尽可能清晰、风格统一。
源文件排版
- Java源文件一般按顺序包含版权、package、import、顶层类，其用空行分隔。
- import包应该按照先安卓、其他商业组织、其他开源第三方、net/org开源组织、最后java的分类顺序出现，并用一个空行分组。
- 一个类的声明部分应该按照类变量、静态初始化块、实例变量、实例初始化块、构造方法、方法的顺序排列，且用空行分隔。
大括号：推荐使用K&R风格
- 条件语句和循环块中要使用大括号。
- 左大括号不换行。
- 右大括号自己单独一行。
- 右大括号后，可以跟逗号、分号等，也可以跟随else、catch、finally等关键字语句。
- 对于空块，除了K&R风格外，也可以在大括号打开后立即关闭，但是要保持空块风格一致。
行宽和可读性
代码行宽上限不取决于屏幕宽度，而是人眼跟踪范围。每行建议不要超过120个窄字符。
换行：换行时建议操作符、连接符放在新的一行
- 当在非赋值运算符处断行时，中断点出现在符号之前。这也适用以下“类似运算符”的符号：
- 点分隔符
. - 方法引用的两个冒号
:: - 类型限定中的&符号
<T extends Foo & Bar> - catch块中的管道
catch (FooException | BarException e)
- 点分隔符
- 方法或构造方法名称与紧跟在其后面的左括号保持在同一行。
- 逗号断点出现在逗号之后。
- 在lambda表达式中，如果箭头后面时单个表达式，可以在箭头后面出现断点，如果箭头后是程序块，可以在大括号后出现断点。
水平空格
代码中的水平空格只能使用单个空格或多个空格的组合：
- 缩进时使用4个空格，不要使用制表符（tab）；代码块的缩进级别应该与上下文代码相同。
- 使用空格突出关键字和重要信息。单个空格应该分隔关键字与其后的左括号、与其前面的大括号，出现在任何二元/三元运算符/类似运算符的两侧，
, : ;或类型转换结束括号)之后使用空格。 - 行尾和空行不应有空格。
- 不建议使用空格使代码垂直对齐。
字面量
数字字面量应该设置合理的后缀来指定数值的类型：
- float类型的字面量，可以使用
F, f作为后缀。 - double类型的字面量，可以使用
D, d作为后缀。 - long类型的字面量，只能使用
L作为后缀，防止l与数字1混淆。
对于较大数值，可以考虑使用数字下划线分隔符来增加代码的可读性，例如30_000_000_000L。