Java代碼之美，從遵循樣式規(guī)范開(kāi)始

作者：京東零售 劉仲偉

在軟件開(kāi)發(fā)的世界里，代碼不僅是程序的基石，更是程序員交流的通用語(yǔ)言。而Java，作為一門(mén)廣泛應(yīng)用于企業(yè)級(jí)應(yīng)用的編程語(yǔ)言，其代碼的可讀性和一致性對(duì)于項(xiàng)目的長(zhǎng)期維護(hù)和團(tuán)隊(duì)協(xié)作至關(guān)重要。本文將帶你探索Java代碼的美學(xué)，揭示那些能夠讓你的代碼既美觀又高效的樣式規(guī)范。無(wú)論是初出茅廬的新手還是經(jīng)驗(yàn)豐富的老手，都能從中獲得靈感，提升編碼的藝術(shù)。

一、為什么要代碼樣式規(guī)范

對(duì)于團(tuán)隊(duì)開(kāi)發(fā)，不同的代碼規(guī)范或不規(guī)范可能引起的問(wèn)題包括但不限于：

1.代碼可讀性，代碼是為了人閱讀的，不是只為了機(jī)器執(zhí)行；

2.代碼format引發(fā)的大量的diff，干擾code review；

3.間接影響代碼質(zhì)量和團(tuán)隊(duì)協(xié)作效率；

在敏捷迭代的軟件開(kāi)發(fā)環(huán)境中，良好的代碼規(guī)范不僅能夠幫助團(tuán)隊(duì)成員快速理解彼此的代碼，減少溝通成本，還能在代碼維護(hù)和擴(kuò)展時(shí)節(jié)省寶貴的時(shí)間。此外，一致的代碼風(fēng)格也是項(xiàng)目專業(yè)性的體現(xiàn)，能夠給代碼審查者和未來(lái)的維護(hù)者留下良好的第一印象。

?

二、探索Java代碼規(guī)范

我們將深入探討Java社區(qū)廣泛認(rèn)可的編碼規(guī)范，包括但不限于Google Java Style和Oracle官方的編碼指南。從命名約定、代碼格式化、注釋的使用，到錯(cuò)誤處理和測(cè)試代碼的編寫(xiě)，每一個(gè)細(xì)節(jié)都是構(gòu)建高質(zhì)量Java代碼的關(guān)鍵。

2.1 業(yè)界Java代碼樣式規(guī)范

a. Google Java Style

Google在github上維護(hù)的多種編程語(yǔ)言的代碼規(guī)范：https://github.com/google/styleguide，其中：

??javaguide.html 是Google對(duì)Java編程語(yǔ)言代碼編碼標(biāo)準(zhǔn)的完整定義；

??intellij-java-google-style.xml 是Google Java代碼規(guī)范文件，適用于Intellij IDEA開(kāi)發(fā)工具；

b. 阿里Java規(guī)范

阿里在 GitHub 上有一個(gè)關(guān)于 Java 開(kāi)發(fā)規(guī)范的倉(cāng)庫(kù) p3c：https://github.com/alibaba/p3c，其中：

??Java開(kāi)發(fā)手冊(cè)(黃山版).pdf 覆蓋編程規(guī)約、異常日志、單元測(cè)試等七個(gè)維度；

??Alibaba Java Coding Guidelines Jetbrains插件市場(chǎng)提供的代碼指導(dǎo)插件， idea-plugin 提供編譯、安裝、使用手冊(cè)；

c. 其它規(guī)范

2.2 規(guī)范選擇與制定

a. 規(guī)范選擇

上面列舉了多項(xiàng)代碼規(guī)范，在決定使用哪種規(guī)范之前，可以考慮三個(gè)方面：

?明確目標(biāo)：使用代碼規(guī)范的目的是什么，只是為了項(xiàng)目?jī)?nèi)代碼風(fēng)格一致，還是為了和其他團(tuán)隊(duì)分享或者其他公司分享或者開(kāi)源？

?使用環(huán)境：開(kāi)發(fā)閱讀代碼的環(huán)境是什么，GitHub、GitLab、公司內(nèi)部的Coding？

?工具支持：code format工具支持情況，code sytle check工具支持情況，編譯工具：maven、gradle，IDE：IntelliJ、Eclipse、VS Code；

綜合上面的三個(gè)方面的考慮，優(yōu)先選擇Google Java Style。

b. 規(guī)范制定

Google Java Style部分代碼樣式團(tuán)隊(duì)難以接受，比如2空格縮進(jìn)等，可以在原始Google Java Style基礎(chǔ)上，適當(dāng)定制化調(diào)整。

?修改intellij-java-google-style.xml中的內(nèi)容：

?修改intellij-java-jd-style.xml文件下載：http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/intellij-java-jd-style.xml?

2.3 規(guī)范使用

代碼樣式規(guī)范的使用分為兩個(gè)方面：

?代碼格式化

?代碼樣式校驗(yàn)

注意：code style 跟 check style 的「配置文件」必須對(duì)應(yīng)，即按照code style format的代碼check style不報(bào)錯(cuò)。

代碼樣式校驗(yàn)

代碼格式化依賴于開(kāi)發(fā)者手動(dòng)進(jìn)行格式化，為達(dá)到團(tuán)隊(duì)/項(xiàng)目代碼樣式規(guī)范的落地，需要有全面的自動(dòng)化的代碼檢查。根據(jù)當(dāng)前業(yè)界推薦，采用Checkstyle作為自動(dòng)化代碼樣式校驗(yàn)工具。

需要對(duì)原始 Google Code Style 的google_checks進(jìn)行定制，以適配上面intellij-java-jd-style.xml的定制。

?修改google_checks中的內(nèi)容：

?修改checkstyle.xml文件下載：http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/checkstyle.xml?

?

除了上述的長(zhǎng)度和縮進(jìn)的代碼樣式校驗(yàn)，Checkstyle還可以配置其它代碼校驗(yàn)，可根據(jù)團(tuán)隊(duì)接受情況予以配置。

?

三、最佳實(shí)踐：如何將規(guī)范融入日常開(kāi)發(fā)

3.1 code style配置&使用

a. IDEA配置code style

在 IntelliJ IDEA下，使用intellij-java-jd-style.xml進(jìn)行代碼格式化之前，需要先進(jìn)行配置。

設(shè)置配置文件，路徑：IntelliJ IDEA→Preference→Editor→Code Style，參考下圖：

導(dǎo)入定制的code style文件：intellij-java-jd-style.xml?

命名Scheme，如圖中JD-Style，并啟用該代碼樣式規(guī)范

b. IDEA使用code style

完成上述配置后，在Mac環(huán)境的IntelliJ IDEA中，可以對(duì)選中的代碼格式化（快捷鍵：Option+Command+L）或者對(duì)選中的文件格式化（快捷鍵：Shift+Option+Command+L）

?

3.2 check style配置&使用

check style的配置和使用有兩種主要方式：

1. 在開(kāi)發(fā)環(huán)境IDE中，開(kāi)發(fā)者配置插件后，可觸發(fā)代碼樣式規(guī)范的檢查，根據(jù)提示項(xiàng)進(jìn)行代碼修改；

2.在maven項(xiàng)目中，配置checkstyle插件，可用命令行觸發(fā)代碼樣式規(guī)范的檢查，集成到CI (Continuous Integration)的自動(dòng)化流水線中；

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窗口進(jìn)行check，可以選擇：

?Check Current File

?Check Module

?Check Project

c. maven配置CheckStyle插件

參考Checkstyle maven插件的官方配置案例：多模塊項(xiàng)目配置，通常我們?cè)陧?xiàng)目中新建build-tools模塊，將checkstyle.xml等配置文件放在這個(gè)模塊的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自動(dòng)生成的配置文件，類似：

    
        project-name
        com.jd.project-name
        1.0.0
    

    4.0.0
    build-tools

配置文件checkstyle.xml、checkstyle-suppressions.xml可以從coding中下載http://xingyun.jd.com/codingRoot/liuzhongwei18/styleguide/blob/master/。

父項(xiàng)目的pom.xml中，增加如下配置：

    ...
    
        ...
        build-tools
    

    
        ...
        3.6.0
    

    
        
            
                
                    
                    org.apache.maven.plugins
                    maven-checkstyle-plugin
                    ${maven.checkstyle.version}
                    
                        build-tools/src/main/resources/checkstyle.xml
                        true
                        checkstyle-report.xml
                        false
                        true
                        target/**
                    
                    
                        
                            checkstyle
                            validate
                            
                                check
                            
                        
                    
                
            
        
        
            
                org.apache.maven.plugins
                maven-checkstyle-plugin
            
        
    
    
        
            
                org.apache.maven.plugins
                maven-checkstyle-plugin
                
                    
                        
                            checkstyle
                        
                    
                
            
        
    

maven-checkstyle-plugin的配置參數(shù)具體可參見(jiàn)checkstyle:check的參數(shù)說(shuō)明。

這里對(duì)幾項(xiàng)配置進(jìn)行說(shuō)明：

?plugins>plugin>executions>execution

?id可以自行決定，這里選擇"checkstyle"；

?phase是綁定到maven lifecycle的哪個(gè)執(zhí)行階段，這里綁定到"validate"上，即執(zhí)行maven validate的時(shí)候會(huì)執(zhí)行該plugin任務(wù)；選擇validate階段可以保障checkstyle:check在代碼編譯之前執(zhí)行，如果checkstyle檢查出違反樣式規(guī)范的問(wèn)題，在代碼編譯之前就會(huì)報(bào)告出來(lái)；

?goals>goal是只綁定執(zhí)行plugin的哪個(gè)任務(wù)，這里綁定的是"check"；

?plugins>plugin>configuration>failOnViolation

?檢查到違反樣式規(guī)范的問(wèn)題，打印出來(lái)，打印的問(wèn)題級(jí)別根據(jù)checkstyle.xml中配置的severity確定；

?將severity級(jí)別配置為error，并將failOnViolation設(shè)為true，檢查到違反樣式規(guī)范的問(wèn)題時(shí)，會(huì)停止maven命令繼續(xù)執(zhí)行；

注意：failOnViolation與failOnError配置項(xiàng)的區(qū)別，failOnError在檢查到問(wèn)題時(shí)立即停止執(zhí)行，failOnViolation在檢查到問(wèn)題時(shí)輸出檢查日志再停止執(zhí)行。

按照上述配置，可達(dá)到在mvn編譯代碼前強(qiáng)制檢查代碼樣式規(guī)范，發(fā)現(xiàn)違反規(guī)范的問(wèn)題，不會(huì)繼續(xù)java的編譯、打包。

d. maven使用CheckStyle插件

運(yùn)行mvn package即可正常打包。

也可以單獨(dú)執(zhí)行命令：

mvn checkstyle:check

注意：為了實(shí)現(xiàn)自動(dòng)化代碼樣式規(guī)范檢查，可以為項(xiàng)目配置行云流水線任務(wù)，設(shè)置代碼評(píng)審的自動(dòng)化檢查：指定流水線做為卡點(diǎn)，指定為卡點(diǎn)的流水線需運(yùn)行成功后MR才允許合并。

?

四、結(jié)語(yǔ)：代碼規(guī)范-團(tuán)隊(duì)協(xié)作的橋梁

最后，我們總結(jié)下Java樣式規(guī)范對(duì)于團(tuán)隊(duì)協(xié)作的重要性，鼓勵(lì)每位開(kāi)發(fā)者將這些規(guī)范內(nèi)化為自己的編碼習(xí)慣。因?yàn)榇a規(guī)范不僅是個(gè)人技藝的體現(xiàn)，更是團(tuán)隊(duì)協(xié)作和項(xiàng)目成功的基石。

通過(guò)閱讀本文，你將不僅了解到Java樣式規(guī)范的重要性，還將掌握如何將這些規(guī)范應(yīng)用到實(shí)際開(kāi)發(fā)中，讓你的代碼變得更加優(yōu)雅和強(qiáng)大。讓我們一起追求編碼的藝術(shù)，用規(guī)范的代碼點(diǎn)亮編程的世界。

?

參考

??京東JAVA代碼規(guī)范-V1.0.pdf?

?JD編碼規(guī)范：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官網(wǎng)：https://checkstyle.org/index.html?

?checkstyle發(fā)布：https://github.com/checkstyle/checkstyle/releases/?

?Apache Maven Checkstyle Plugin: https://maven.apache.org/plugins/maven-checkstyle-plugin/usage.html

審核編輯 黃宇