跳到正文
Code Review

← C / C++ / Java 来源

google-styleguide · 来源归档

保留原始资料供追溯;实际扫描仅使用对应语言中当前生效的检查项。来源中的建议、示例及适用边界按各自说明解释。

下载原始 Markdown

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.1if、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。
  • 对于上游允许多个写法的情形,不强制选择其中一个;涉及例外时回查保存的完整英文原文。