Java代码之美，从遵循样式规范开始

作者：京东零售 刘仲伟

在软件开发的世界里，代码不仅是程序的基石，更是程序员交流的通用语言。而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	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的配置和使用有两种主要方式：

1. 在开发环境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-module

build-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 >

    
        < 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的配置参数具体可参见checkstyle:check的参数说明。

这里对几项配置进行说明：

•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样式规范的重要性，还将掌握如何将这些规范应用到实际开发中，让你的代码变得更加优雅和强大。让我们一起追求编码的艺术，用规范的代码点亮编程的世界。



参考

•京东JAVA代码规范-V1.0.pdf

•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

审核编辑 黄宇