作者：京东零售 刘仲伟
在软件开发的世界里，代码不仅是程序的基石，更是程序员交流的通用语言。而Java，作为一门广泛应用于企业级应用的编程语言，其代码的可读性和一致性对于项目的长期维护和团队协作至关重要。本文将带你探索Java代码的美学，揭示那些能够让你的代码既美观又高效的样式规范。无论是初出茅庐的新手还是经验丰富的老手，都能从中获得灵感，提升编码的艺术。
一、为什么要代码样式规范
对于团队开发，不同的代码规范或不规范可能引起的问题包括但不限于：
1.代码可读性，代码是为了人阅读的，不是只为了机器执行；
2.代码format引发的大量的diff，干扰code review；
3.间接影响代码质量和团队协作效率；
在敏捷迭代的软件开发环境中，良好的代码规范不仅能够帮助团队成员快速理解彼此的代码，减少沟通成本，还能在代码维护和扩展时节省宝贵的时间。此外，一致的代码风格也是项目专业性的体现，能够给代码审查者和未来的维护者留下良好的第一印象。
二、探索Java代码规范
我们将深入探讨Java社区广泛认可的编码规范，包括但不限于Google Java Style和Oracle官方的编码指南。从命名约定、代码格式化、注释的使用，到错误处理和测试代码的编写，每一个细节都是构建高质量Java代码的关键。
2.1 业界Java代码样式规范
a. Google Java Style
Google在github上维护的多种编程语言的代码规范：https://github.com/google/styleguide，其中：
•javaguide.html 是Google对Java编程语言代码编码标准的完整定义；
•intellij-java-google-style.xml 是Google Java代码规范文件，适用于Intellij IDEA开发工具；
b. 阿里Java规范
阿里在 GitHub 上有一个关于 Java 开发规范的仓库 p3c：https://github.com/alibaba/p3c，其中：
•Java开发手册(黄山版).pdf 覆盖编程规约、异常日志、单元测试等七个维度；
•Alibaba Java Coding Guidelines Jetbrains插件市场提供的代码指导插件， idea-plugin 提供编译、安装、使用手册；
c. 其它规范
| 公司/组织 | Style Guide |
|---|---|
| Sun/Oracle | The Original Sun Java Style Guide |
| Andriod | Android Open Source Project (AOSP) Style Guide |
| Twitter’s Java Style Guide | |
| Coderanch | The CodeRanch Style Guide |
2.2 规范选择与制定
a. 规范选择
上面列举了多项代码规范，在决定使用哪种规范之前，可以考虑三个方面：
•明确目标：使用代码规范的目的是什么，只是为了项目内代码风格一致，还是为了和其他团队分享或者其他公司分享或者开源？
•使用环境：开发阅读代码的环境是什么，GitHub、GitLab、公司内部的Coding？
•工具支持：code format工具支持情况，code sytle check工具支持情况，编译工具：maven、gradle，IDE：IntelliJ、Eclipse、VS Code；
综合上面的三个方面的考虑，优先选择Google Java Style。
b. 规范制定
Google Java Style部分代码样式团队难以接受，比如2空格缩进等，可以在原始Google Java Style基础上，适当定制化调整。
•修改intellij-java-google-style.xml中的内容：
| option | previous value | modified value | note |
|---|---|---|---|
| INDENT_SIZE | 2 | 4 | 行缩进空格数 |
| TAB_SIZE | 2 | 4 | TAB空格数 |
| CONTINUATION_INDENT_SIZE | 4 | 8 | 换行缩进空格数 |
| RIGHT_MARGIN | 100 | 120 | 单行长度 |
| JD_PRESERVE_LINE_FEEDS | 无 | TRUE | JavaDoc 中，保留手动的换行 |
| KEEP_LINE_BREAKS | 无 | TRUE | Java代码中，保留手动的换行 |
•修改intellij-java-jd-style.xml文件下载：http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/intellij-java-jd-style.xml
2.3 规范使用
代码样式规范的使用分为两个方面：
•代码格式化
•代码样式校验
| 规范使用 | 英文 | 使用对象 | 使用方式 | 说明 | 配置文件 |
|---|---|---|---|---|---|
| 代码格式化 | code style | 开发者 | IDE手动 | 定义代码风格 | intellij-java-jd-style.xml |
| 代码样式校验 | check style | 团队 | 自动化 | 校验代码风格 | checkstyle.xml |
注意：code style 跟 check style 的「配置文件」必须对应，即按照code style format的代码check style不报错。
代码样式校验
代码格式化依赖于开发者手动进行格式化，为达到团队/项目代码样式规范的落地，需要有全面的自动化的代码检查。根据当前业界推荐，采用Checkstyle作为自动化代码样式校验工具。
需要对原始 Google Code Style 的google_checks进行定制，以适配上面intellij-java-jd-style.xml的定制。
•修改google_checks中的内容：
| module | property | previous value | modified value | note |
|---|---|---|---|---|
| LineLength | max | 100 | 120 | 单行长度 |
| Indentation | basicOffset braceAdjustment caseIndent throwsIndent lineWrappingIndentation arrayInitIndent | 2 2 2 4 4 2 | 4 0 4 4 4 4 | 使用checkstyle默认缩进风格 |
•修改checkstyle.xml文件下载：http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/checkstyle.xml
除了上述的长度和缩进的代码样式校验，Checkstyle还可以配置其它代码校验，可根据团队接受情况予以配置。
| module | property | default value | note |
|---|---|---|---|
| FileLength | max | 2000 | 单个文件长度 |
| MethodLength | max | 150 | 单个方法长度 |
| ParameterNumber | max | 7 | 方法的参数个数 |
| ModifierOrder | Java语言规范 | ||
| NestedIfDepth | max | 1 | 检查if-else嵌套层数 |
| NestedTryDepth | max | 1 | 检查try-catch-finally嵌套层数 |
| ReturnCount | max | 2 | 一个方法最多有return的数量 |
| CyclomaticComplexity | max | 10 | 方法圈复杂度 |
| MagicNumber | 检查魔法数字，未被定义为常量的数值 | ||
| ... | https://checkstyle.org/checks.html |
三、最佳实践：如何将规范融入日常开发
3.1 code style配置&使用
a. IDEA配置code style
在 IntelliJ IDEA下，使用intellij-java-jd-style.xml进行代码格式化之前，需要先进行配置。
设置配置文件，路径：IntelliJ IDEA→Preference→Editor→Code Style，参考下图：
导入定制的code style文件：intellij-java-jd-style.xml
命名Scheme，如图中JD-Style，并启用该代码样式规范
b. IDEA使用code style
完成上述配置后，在Mac环境的IntelliJ IDEA中，可以对选中的代码格式化（快捷键：Option+Command+L）或者对选中的文件格式化（快捷键：Shift+Option+Command+L）
3.2 check style配置&使用
check style的配置和使用有两种主要方式：
- 在开发环境IDE中，开发者配置插件后，可触发代码样式规范的检查，根据提示项进行代码修改；
2.在maven项目中，配置checkstyle插件，可用命令行触发代码样式规范的检查，集成到CI (Continuous Integration)的自动化流水线中；
a. IDEA配置CheckStyle插件
在 IntelliJ IDEA下，安装Plugin，路径：IntelliJ IDEA→Preference→Plugins，参考下图：
下载配置文件checkstyle.xml，配置CheckStyle-IDEA插件，路径：IntelliJ IDEA→Preference→Tools→Checkstyle，增加自定义配置文件并命名，参考下图：
b. IDEA使用CheckStyle插件
安装配置CheckStyle插件后，工具窗口增加了CheckStyle Tab，在CheckStyle窗口进行check，可以选择：
•Check Current File
•Check Module
•Check Project
c. maven配置CheckStyle插件
参考Checkstyle maven插件的官方配置案例：多模块项目配置，通常我们在项目中新建build-tools模块，将checkstyle.xml等配置文件放在这个模块的resources目录下。
project-name
| -- pom.xml
| -- build-tools
| | -- pom.xml
| | -- src
| | | -- main
| | | -- resources
| | | -- checkstyle.xml
| | | -- checkstyle-suppressions.xml
| -- core
| -- gui
| -- other-modulebuild-tools模块的pom.xml使用IDEA自动生成的配置文件，类似：
<?xml version="1.0" encoding="UTF-8"?>
<project>
<parent>
<artifactId>project-name</artifactId>
<groupId>com.jd.project-name</groupId>
<version>1.0.0</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>build-tools</artifactId>
</project>配置文件checkstyle.xml、checkstyle-suppressions.xml可以从coding中下载http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/。
父项目的pom.xml中，增加如下配置：
<project>
...
<modules>
...
<module>build-tools</module>
</modules>
<properties>
...
<maven.checkstyle.version>3.6.0</maven.checkstyle.version>
</properties>
<build>
<pluginManagement>
<plugins>
<plugin>
<!-- Approach followed here is roughly the same as mentioned here:
https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html
-->
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>${maven.checkstyle.version}</version>
<configuration>
<configLocation>build-tools/src/main/resources/checkstyle.xml</configLocation>
<includeTestSourceDirectory>true</includeTestSourceDirectory>
<outputFile>checkstyle-report.xml</outputFile>
<consoleOutput>false</consoleOutput>
<failOnViolation>true</failOnViolation>
<excludes>target/**</excludes>
</configuration>
<executions>
<execution>
<id>checkstyle</id>
<phase>validate</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<reportSets>
<reportSet>
<reports>
<report>checkstyle</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</project>maven-checkstyle-plugin的配置
这里对几项配置进行说明：
•plugins>plugin>executions>execution
◦id可以自行决定，这里选择"checkstyle"；
◦phase是绑定到maven lifecycle的哪个执行阶段，这里绑定到"validate"上，即执行maven validate的时候会执行该plugin任务；选择validate阶段可以保障checkstyle:check在代码编译之前执行，如果checkstyle检查出违反样式规范的问题，在代码编译之前就会报告出来；
◦goals>goal是只绑定执行plugin的哪个任务，这里绑定的是"check"；
•plugins>plugin>configuration>failOnViolation
◦检查到违反样式规范的问题，打印出来，打印的问题级别根据checkstyle.xml中配置的severity确定；
◦将severity级别配置为error，并将failOnViolation设为true，检查到违反样式规范的问题时，会停止maven命令继续执行；
注意：failOnViolation与failOnError配置项的区别，failOnError在检查到问题时立即停止执行，failOnViolation在检查到问题时输出检查日志再停止执行。
按照上述配置，可达到在mvn编译代码前强制检查代码样式规范，发现违反规范的问题，不会继续java的编译、打包。
d. maven使用CheckStyle插件
运行mvn package即可正常打包。
也可以单独执行命令：
mvn checkstyle:check注意：为了实现自动化代码样式规范检查，可以为项目配置行云流水线任务，设置代码评审的自动化检查：指定流水线做为卡点，指定为卡点的流水线需运行成功后MR才允许合并。
四、结语：代码规范-团队协作的桥梁
最后，我们总结下Java样式规范对于团队协作的重要性，鼓励每位开发者将这些规范内化为自己的编码习惯。因为代码规范不仅是个人技艺的体现，更是团队协作和项目成功的基石。
通过阅读本文，你将不仅了解到Java样式规范的重要性，还将掌握如何将这些规范应用到实际开发中，让你的代码变得更加优雅和强大。让我们一起追求编码的艺术，用规范的代码点亮编程的世界。
参考
•JD编码规范：https://doc.jd.com/base/eos-doc/system-rule/JD%E7%BC%96%E7%A0%81%E8%A7%84%E8%8C%83/Java/
•Jetbrains Java code style: https://www.jetbrains.com/help/idea/code-style-java.html
•checkstyle官网：https://checkstyle.org/index.html
•checkstyle发布：https://github.com/checkstyle/checkstyle/releases/
•Apache Maven Checkstyle Plugin: https://maven.apache.org/plugins/maven-checkstyle-plugin/usage.html
