开发者社区 > 博文 > Java代码之美,从遵循样式规范开始
分享
  • 打开微信扫码分享

  • 点击前往QQ分享

  • 点击前往微博分享

  • 点击复制链接

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

  • te****
  • 2024-11-25
  • IP归属:北京
  • 100浏览

    在软件开发的世界里,代码不仅是程序的基石,更是程序员交流的通用语言。而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,其中:

    b. 阿里Java规范

    阿里在 GitHub 上有一个关于 Java 开发规范的仓库 p3c:https://github.com/alibaba/p3c,其中:

    c. 其它规范

    公司/组织Style Guide
    Sun/OracleThe Original Sun Java Style Guide
    AndriodAndroid Open Source Project (AOSP) Style Guide
    TwitterTwitter’s Java Style Guide
    CoderanchThe 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中的内容:
    optionprevious valuemodified valuenote
    INDENT_SIZE24行缩进空格数
    TAB_SIZE24TAB空格数
    CONTINUATION_INDENT_SIZE48换行缩进空格数
    RIGHT_MARGIN100120单行长度
    JD_PRESERVE_LINE_FEEDSTRUEJavaDoc 中,保留手动的换行
    KEEP_LINE_BREAKSTRUEJava代码中,保留手动的换行

    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的定制。

    modulepropertyprevious valuemodified valuenote
    LineLengthmax100120单行长度
    IndentationbasicOffset
    braceAdjustment
    caseIndent
    throwsIndent
    lineWrappingIndentation
    arrayInitIndent
    2
    2
    2
    4
    4
    2
    4
    0
    4
    4
    4
    4
    使用checkstyle默认缩进风格


    除了上述的长度和缩进的代码样式校验,Checkstyle还可以配置其它代码校验,可根据团队接受情况予以配置。

    modulepropertydefault valuenote
    FileLengthmax2000单个文件长度
    MethodLengthmax150单个方法长度
    ParameterNumbermax7方法的参数个数
    ModifierOrderJava语言规范
    NestedIfDepthmax1检查if-else嵌套层数
    NestedTryDepthmax1检查try-catch-finally嵌套层数
    ReturnCountmax2一个方法最多有return的数量
    CyclomaticComplexitymax10方法圈复杂度
    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

    命名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 IDEAPreferencePlugins,参考下图:

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

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


    参考

    文章数
    1
    阅读量
    0

    作者其他文章