Google Java Style Guide:中文规则要点
来源:Google 及其贡献者的 Google Java Style Guide(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md)。保存日期:2026-11-13。固定提交:52f2e7406a802778e44b92694d4aead252b09091。
本文件按原章节归纳主要规则,压缩了示例与细节;完整规则保存在 英文原文。章节编号属于上游,不是新建的缺陷编号。中文文字按 CC BY 3.0 提供,原文代码示例按 Apache 2.0 提供;完整归属与使用边界见 README。
1. 适用范围与术语
原文:第 1 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s1-introduction)。
- “类”包括普通类、record、enum、接口和注解类型;“成员”包括嵌套类、字段、方法和构造器。
- 实现注释和 Javadoc 分开约束。
- 上游示例是非规范性的:示例中的可选格式不能被提升为强制要求。
- 本地使用时需先核对项目语言版本。模块、record、文本块、switch 表达式、未命名变量和 Markdown Javadoc 等仅在实际工具链支持时适用。这是本地适用性说明,不是要求所有项目升级 Java。
2. 源文件基础
原文:第 2 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s2-source-file-basics)。
| 原章节 | 规则要点 |
|---|---|
| 2.1 | 包含类的源文件使用唯一顶层类的名称,加 .java 后缀;大小写保持一致。 |
| 2.2 | 源文件使用 UTF-8。 |
| 2.3.1 | 除行终止序列外,源码中直接使用的空白字符限于 ASCII 空格 0x20;不使用 Tab 缩进,字面量中的其他空白使用转义。 |
| 2.3.2 | 对具有专用转义序列的字符使用该序列,不用对应的八进制或 Unicode 转义替代。 |
| 2.3.3 | 其他非 ASCII 字符可直接书写或使用 Unicode 转义,以清晰易懂为准;不鼓励在字符串和注释之外使用 Unicode 转义,必要时说明不可打印字符的含义。 |
3. 源文件结构
原文:第 3 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s3-source-file-structure)。
- 普通文件依次排列版权/许可声明(如有)、package、imports、唯一顶层类;存在的相邻部分之间恰好一个空行。
package-info.java不包含类声明;module-info.java不含 package,使用模块声明代替类声明。- 3.2:普通源文件有 package 声明,不使用 compact source files;package 声明不折行,也不受 100 字符行宽限制。
- 3.3.1 / 3.3.1.1:不用通配符 import,包括静态通配符;不用 module import。
- 3.3.2 / 3.3.3:import 不折行;静态 import 在前、普通 import 在后,两组之间一个空行,组内不额外插入空行,按导入名称的 ASCII 顺序排序。
- 3.3.4:静态嵌套类使用普通 import,不使用 static import 导入类。
- 3.4.1:每个顶层类单独占一个源文件。
- 3.4.2:类成员和初始化块采用可以解释的逻辑顺序;不规定适用于所有类的唯一顺序。相同名字的方法重载、多个构造器各自连续排列,即使访问修饰符或 static 属性不同也不拆散。
- 3.5.1:模块指令依次分为 requires、exports、opens、uses、provides 五组,存在的相邻组间一个空行。
4. 格式
原文:第 4 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s4-formatting)。
4.1–4.7 通用格式
| 原章节 | 规则要点与边界 |
|---|---|
| 4.1.1 | if、else、for、do、while 即使只有一条语句或为空也使用花括号。lambda 等其他可选花括号仍可省略。 |
| 4.1.2 | 非空块采用 K&R 风格:左花括号通常不另起一行,块内换行,右花括号前换行;右花括号后是否换行取决于后续是否接 else、逗号等。独立局部作用域块等例外查原文。 |
| 4.1.3 | 独立空块可写成 {};if/else、try/catch/finally 这类多块语句中的空块不能用该简写。 |
| 4.2 / 4.3 | 块缩进每层增加 2 个空格;每条语句之后换行。 |
| 4.4 | 通常每行最多 100 个 Unicode 码点;package、import、文本块内容、不可合理拆分的 URL、供复制执行的注释命令等有例外。 |
| 4.5.1 | 优先在较高语法层级折行;非赋值运算符通常在符号前折行,赋值运算符通常在符号后折行但两种均可。方法名与左圆括号不拆开,逗号留在前一项末尾。lambda/switch 箭头附近的折行另有例外。 |
| 4.5.2 | 续行相对原行至少增加 4 个空格;语法并列的续行保持一致缩进。 |
| 4.6.1 | 类成员/初始化块间通常一个空行;连续字段、枚举常量存在例外。允许为逻辑分组增加空行,连续多个空行不是必需或推荐的格式。 |
| 4.6.2 | 关键字与后续左圆括号之间、二元/三元运算符两侧、lambda/switch 箭头两侧等使用空格;成员访问点号和方法引用 :: 两侧不加空格。完整空格位置及例外见原文。 |
| 4.6.3 | 不要求用额外空格做纵向对齐,也不要求保持已有对齐;不为重新对齐而扩大无关修改。 |
| 4.7 | 对容易误解的表达式使用分组括号;不能假设所有读者都记得运算符优先级。 |
4.8 特定结构
- 4.8.1 枚举:枚举常量逗号后可换行,也可用空行分组。没有方法、且常量上没有文档的简单枚举,可按数组初始化器方式紧凑排版。
- 4.8.2 变量:一次声明一个变量,for 头部例外;局部变量靠近首次使用点声明,以缩小作用域,通常同时或紧接着初始化。
- 4.8.3 数组:初始化器可按块排版;方括号跟随类型,例如
String[] args,不使用String args[]。 - 4.8.4 switch:case 标签比 switch 缩进 2 个空格;旧式冒号分支中的语句再缩进 2 个空格。旧式分支若可能贯穿到下一语句组,需要说明贯穿;最后一组无需该注释。所有 switch 都应穷尽取值,必要时增加 default;覆盖所有枚举值等情况可以不写 default。switch 表达式使用箭头形式。
- 4.8.5 注解:TYPE_USE 注解紧邻被注解类型。类、package、module 的声明注解置于文档之后,每个一行;方法和构造器一般同样处理,但单个无参数注解可与签名首行同行。字段可以一行放多个注解;参数和局部变量没有额外通用排版要求,TYPE_USE 规则除外。
- 4.8.6 实现注释:与周围代码同级缩进;多行
/* ... */的星号对齐,不使用字符画框。TODO 使用统一格式TODO: 上下文链接 - 说明,优先链接问题记录,不只写负责人姓名;有未来移除条件时注明明确日期或事件。 - 4.8.7 修饰符:出现的类和成员修饰符依次为 public、protected、private、abstract、default、static、final、sealed、non-sealed、transient、volatile、synchronized、native、strictfp;requires 指令的修饰符按 transitive、static 排列。仅约束合法组合中实际出现的修饰符顺序。
- 4.8.8 数值字面量:long 后缀使用大写
L,不用容易与数字 1 混淆的小写l。 - 4.8.9 文本块:开始和结束的三个双引号各自另起一行并保持相同缩进;开始行可按正常规则缩进或顶格。正文至少缩进到引号所在列,正文内容可以超过行宽限制。
5. 命名
原文:第 5 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s5-naming)。
| 原章节 | 对象 | 规则要点 |
|---|---|---|
| 5.1 | 通用标识符 | 仅 ASCII 字母、数字及限定情形下的下划线;不用 mName、s_name、name_、kName 这类特殊前后缀。 |
| 5.2.1 | 包和模块 | 名称中的单词只用小写字母和数字直接连接,不用下划线;层级仍用点分隔。 |
| 5.2.2 | 类、接口、测试类 | 类型名使用 UpperCamelCase;类通常是名词短语,接口也可用形容词。测试类以 Test 结尾,测试单个类时通常为被测类名加 Test。 |
| 5.2.3 | 方法 | lowerCamelCase,通常为动词短语;JUnit 测试方法可用下划线分隔各个 lowerCamelCase 逻辑片段。 |
| 5.2.4 | 常量 | UPPER_SNAKE_CASE;此处指内容深度不可变、方法无可观察副作用的 static final 字段。仅有 static final 不足以判定为常量。 |
| 5.2.5 | 非常量字段 | lowerCamelCase,包含指向可变对象的 static final 字段。 |
| 5.2.6 | 参数 | lowerCamelCase;公开方法避免单字符参数名。 |
| 5.2.7 | 局部变量 | lowerCamelCase;即使 final 且不可变,也不采用常量命名。 |
| 5.2.8 | 类型变量 | 单个大写字母,可跟一个数字,例如 T、T2;或 UpperCamelCase 名称加 T,例如 RequestT。 |
| 5.2.9 | 未命名变量 | 在语言允许的场景可以使用 _;这不是对不支持该语法的旧项目的要求。 |
| 5.3 | 驼峰转换 | 先按单词拆分,再按普通单词处理缩略词,例如 XmlHttpRequest、newCustomerId;不机械保留 XML、ID 全大写。具体词形例外见原文。 |
6. 编程惯例
原文:第 6 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s6-programming-practices)。
- 6.1:在合法位置使用
@Override,包括重写父类方法、实现接口方法、接口重声明父接口方法和显式 record 访问器。父方法已标记@Deprecated时可省略。 - 6.2:捕获异常后通常应作出处理;确实可以不处理时,在 catch 中说明原因。是否符合业务恢复、错误传播和中断语义还需另行审查,不能仅凭存在日志就判定处理正确。
- 6.3:需要限定静态成员时,用类名限定,不通过实例引用或返回实例的表达式访问。
- 6.4:不重写
Object.finalize()。
7. Javadoc
原文:第 7 章(原始出处:https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md#s7-javadoc)。
- 7.1.1:允许传统
/** ... */和 Markdown///Javadoc;后者需实际工具链支持。传统单行形式只在完整注释可放入一行且没有@param等块标签时使用。 - 7.1.2:传统 Javadoc 段落间用只有星号的空行分隔,第一段之后的普通段落以
<p>紧接正文开始;其他 HTML 块级元素前不加<p>。Markdown Javadoc 使用只有///的空行分段。 - 7.1.3:使用的块标签按
@param、@return、@throws、@deprecated排列,这四类标签都不能只有标签而没有描述;传统格式的标签续行相对@至少缩进 4 个空格,Markdown 格式恰好 2 个空格。 - 7.2:开头提供简短摘要片段,使类/方法索引中能读懂用途。摘要不是只有
@return的标签行,也不是冗长的 “This method returns…” 句式。 - 7.3:至少给可见的类、成员和 record 组件提供 Javadoc。顶层 public 类可见;public/protected 成员还要求所在类可见;record 组件要求所在 record 可见。
- 7.3.1 / 7.3.2:确实简单且自解释的成员/record 组件可以省略,但不能省略调用者需要理解的关键术语或行为;重写方法不一定重复编写 Javadoc。
- 7.3.4:其他位置按需要添加。若注释用于说明类/成员整体用途或行为,使用 Javadoc;非强制位置的 Javadoc 推荐遵循格式要求,但上游没有将所有格式条款设为强制。
本地评审时的分级
以下是本地使用建议,不属于 Google 原文规则:
- 未处理异常造成失败被掩盖、switch 分支遗漏造成错误结果等,按实际证据报告代码质量问题。
- 命名、import 顺序、缩进、行宽等,在项目已经采用 Google Style 时报告规范问题,否则只作风格参考。
- 不因本指南提供了新语法示例,就要求 Java 8/11 项目改成 record、文本块、未命名变量或 Markdown Javadoc。
- 对于上游允许多个写法的情形,不强制选择其中一个;涉及例外时回查保存的完整英文原文。