# Google Java Style Guide：中文规则要点

来源：Google 及其贡献者的 [Google Java Style Guide](https://github.com/google/styleguide/blob/52f2e7406a802778e44b92694d4aead252b09091/javaguide.md)。保存日期：2026-11-13。固定提交：`52f2e7406a802778e44b92694d4aead252b09091`。

本文件按原章节归纳主要规则，压缩了示例与细节；完整规则保存在 [英文原文](upstream/google-styleguide-original.md)。章节编号属于上游，不是新建的缺陷编号。中文文字按 [CC BY 3.0](licenses/google-styleguide-CC-BY-3.0.txt) 提供，原文代码示例按 [Apache 2.0](licenses/Apache-2.0.txt) 提供；完整归属与使用边界见 [README](README.md)。

## 1. 适用范围与术语

原文：[第 1 章](upstream/google-styleguide-original.md#s1-introduction)。

- “类”包括普通类、record、enum、接口和注解类型；“成员”包括嵌套类、字段、方法和构造器。
- 实现注释和 Javadoc 分开约束。
- 上游示例是非规范性的：示例中的可选格式不能被提升为强制要求。
- 本地使用时需先核对项目语言版本。模块、record、文本块、switch 表达式、未命名变量和 Markdown Javadoc 等仅在实际工具链支持时适用。这是本地适用性说明，不是要求所有项目升级 Java。

## 2. 源文件基础

原文：[第 2 章](upstream/google-styleguide-original.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 章](upstream/google-styleguide-original.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 章](upstream/google-styleguide-original.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 章](upstream/google-styleguide-original.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 章](upstream/google-styleguide-original.md#s6-programming-practices)。

- **6.1**：在合法位置使用 `@Override`，包括重写父类方法、实现接口方法、接口重声明父接口方法和显式 record 访问器。父方法已标记 `@Deprecated` 时可省略。
- **6.2**：捕获异常后通常应作出处理；确实可以不处理时，在 catch 中说明原因。是否符合业务恢复、错误传播和中断语义还需另行审查，不能仅凭存在日志就判定处理正确。
- **6.3**：需要限定静态成员时，用类名限定，不通过实例引用或返回实例的表达式访问。
- **6.4**：不重写 `Object.finalize()`。

## 7. Javadoc

原文：[第 7 章](upstream/google-styleguide-original.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。
- 对于上游允许多个写法的情形，不强制选择其中一个；涉及例外时回查保存的完整英文原文。
