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

京东云开发者
• 阅读 155

作者:京东零售 刘仲伟

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 IDEAPreferenceEditorCode Style,参考下图:

导入定制的code style文件:intellij-java-jd-style.xml

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



命名Scheme,如图中JD-Style,并启用该代码样式规范

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

b. IDEA使用code style

完成上述配置后,在Mac环境的IntelliJ IDEA中,可以对选中的代码格式化(快捷键:Option+Command+L)或者对选中的文件格式化(快捷键:Shift+Option+Command+L)

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

3.2 check style配置&使用

check style的配置和使用有两种主要方式:

  1. 在开发环境IDE中,开发者配置插件后,可触发代码样式规范的检查,根据提示项进行代码修改;

2.在maven项目中,配置checkstyle插件,可用命令行触发代码样式规范的检查,集成到CI (Continuous Integration)的自动化流水线中;

a. IDEA配置CheckStyle插件

在 IntelliJ IDEA下,安装Plugin,路径:IntelliJ IDEAPreferencePlugins,参考下图:

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

下载配置文件checkstyle.xml,配置CheckStyle-IDEA插件,路径:IntelliJ IDEAPreferenceToolsCheckstyle,增加自定义配置文件并命名,参考下图:

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

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>

    <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的配置参数具体可参见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命令继续执行;

注意:failOnViolationfailOnError配置项的区别,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

点赞
收藏
评论区
推荐文章
C语言编程,初学者必学代码规范,你知道哪些?
C语言编程,初学者必学代码规范,你知道哪些?一个好的程序编写规范是编写高质量程序的保证。清晰、规范的源程序不仅仅是方便阅读,更重要的是能够便于检查错误,提高调试效率,从而最终保证软件的质量和可维护性。本文章适合编程初学者,对于具有一定工程项目开发经验的程序员,建议学习C语言程序代码编写规范—高级版。1代码书写规范1.1函数定义花括号:每个函数的定义和说明
Wesley13 Wesley13
3年前
Java 概述
Java概述Java编程语言是一种通用的、并行的、基于类的、面向对象的语言。它被设计得非常简单,这样程序员可以在该语言上流畅的交流。Java编程语言与C和C有关联,但组织却截然不同,其中也省略了其他语言的一些用法,比如指针。它的目的是作为一个生产性语言,而不是一个研究性语言,因此,在设计上避免了包括新的和未经考验的功能。
Wesley13 Wesley13
3年前
Java代码编写规范(转)
编码规范1前言为确保系统源程序可读性,从而增强系统可维护性,java编程人员应具有基本类似的编程风格,兹制定下述Java编程规范,以规范系统Java部分编程。系统继承的其它资源中的源程序也应按此规范作相应修改。2适用范围本文档将作为java编程人员软件开发的编程格式规范。在项目Java部分的编码、测试及维护过程中,要求严格遵守
linbojue linbojue
8个月前
建立web前端开发规范的重要性(浅谈前端开发的重要性以及前景分析)
一个好的程序员肯定是要能书写可维护的代码,而不是一次性的代码,怎么能让团队当中的其他人,甚至过一段时间之后的你,再看自己某个时期写的代码,依然能看懂?这就涉及到规范你的代码了。一、规范代码的好处1、从根本上降低开发成本:提高代码整体的可读性、可维护性、可复
爱学it学无止境 爱学it学无止境
4个月前
看动画,轻松学习23种C++设计模式完结无密
C设计模式深度解析:提升代码质量与可维护性的关键在C软件开发中,设计模式作为一种经过验证的软件开发方法,被广泛用于解决常见的设计问题,提高代码的可读性、可维护性和可扩展性。本文将深入探讨C中几种常用的设计模式,分析其原理、应用场景及实现方式,以
京东云开发者 京东云开发者
1个月前
Code Review:探索工程实践之道
作者:京东物流冯志文前言本文参考《京东JAVA代码规范V1.1》\&Google代码评审工程实践方法论,结合团队代码评审的实践经验整理成文档,这份文档是我们团队集体经验的结晶。我相信公司其他部门也有类似的经验和最佳实践。希望通过互相交流和学习,共同提高代码
京东云开发者 京东云开发者
1个月前
Java方法设计原则与实践:从Effective Java到团队案例
作者:京东物流京东物流背景本文通过阅读《EffectiveJava》、《CleanCode》、《京东JAVA代码规范》等代码质量书籍,结合团队日常代码实践案例进行整理,抛砖引玉、分享一些在编写高质量代码方面的见解和经验。这些书籍提供了丰富的理论知识,而团队
小万哥 小万哥
1年前
C++中的可移植性和跨平台开发
在当今软件开发行业中,跨平台开发已经成为了一种非常流行的方式。C作为一门强大的编程语言,也被广泛应用于跨平台开发中。然而,由于不同操作系统的差异和限制,C在不同的平台上的表现可能会有所不同。为了解决这个问题,我们需要优化C代码的可移植性,以便在
小万哥 小万哥
1年前
Git入门指南:从新手到高手的完全指南
Git是一种强大的分布式版本控制系统,广泛应用于软件开发中。它的使用不仅可以帮助开发团队更好地管理代码,还可以提高团队协作效率和代码质量。随着软件开发的不断发展,版本控制成为了程序员必备的一项技能。Git作为最流行的分布式版本控制系统,被广泛地应用于软件开