深入淺出系列之代碼可讀性

原創(chuàng)聲明：該文章是個(gè)人在項(xiàng)目中親歷后的經(jīng)驗(yàn)總結(jié)和分享，如有搬運(yùn)需求請(qǐng)注明出處。 這是“深入淺出系列”文章的第一篇，主要記錄和分享程序設(shè)計(jì)的一些思想和方法論，如果讀者覺(jué)得所有受用，還請(qǐng)“一鍵三連”，這是對(duì)我最大的鼓勵(lì)。

一、老生常談，到底啥是可讀性

一句話：見(jiàn)名知其義。有人說(shuō)好的代碼必然有清晰完整的注釋?zhuān)也环裾J(rèn)；也有人說(shuō)代碼即注釋?zhuān)谴a簡(jiǎn)潔之道的最高境界，我也不否認(rèn)。但我都不完全接受，如果照搬前者，有人會(huì)在每個(gè)方法、每個(gè)循環(huán)、每個(gè)判斷都添加大量注釋?zhuān)瑢?duì)于一個(gè)表達(dá)不嚴(yán)謹(jǐn)?shù)腸oder來(lái)說(shuō)，代碼與漢字可能詞不達(dá)意；而且，一旦代碼邏輯發(fā)生變化，注釋改不改？對(duì)于后者，英語(yǔ)水平可能也就是個(gè)半吊子，動(dòng)詞名詞不區(qū)分，真能做到代碼即注釋的有多少人？

二、罵歸罵，總歸要硬著頭皮干

先來(lái)舉個(gè)簡(jiǎn)單例子：

public StepExitEnum doExecute(StepContext stepContext) throws Exception {
    String targetFilePath = this.getOriginFilePath(stepContext.getJobContext());//獲取目標(biāo)路徑
    File targetDir = new File(targetFilePath);
    if (!targetDir.exists()) {
        targetDir.mkdirs();//如果不存在目錄則創(chuàng)建
    }

    String encryptedFilePath = this.getEncryptedFilePath(stepContext.getJobContext());//獲取加密文件路徑
    String fileName = this.getFileName(stepContext);//獲取文件名
    File[] encryptedFiles = new File(encryptedFilePath).listFiles(this.buildFilenameFilter(fileName));//過(guò)濾文件

    FileEncryptor dencryptor = this.buildFileEncryptor(stepContext);//創(chuàng)建FileEncryptor
    Stream.of(encryptedFiles)
            .forEach(encryptFile -> {
                File targetFile = new File(targetFilePath, encryptFile.getName());
                dencryptor.invoke(encryptFile, targetFile);//解密文件
            });

    return StepExitEnum.CONTINUING;
}

這種代碼很常見(jiàn)，耐著性子其實(shí)也容易看懂：創(chuàng)建目錄->讀取加密文件->解密文件，就當(dāng)前來(lái)說(shuō)其實(shí)滿足了業(yè)務(wù)需求也就可以了，但不夠優(yōu)雅，從長(zhǎng)期來(lái)講，這會(huì)產(chǎn)生bad smell，首先，“如果不存在目錄則創(chuàng)建”、“獲取文件名”這類(lèi)注釋有何意義？有可能這是coder當(dāng)時(shí)的方案思路，但這里真的需要嗎？它確確實(shí)實(shí)影響我的注意力了，但我沒(méi)有獲取到任何有價(jià)值信息；其次，若想要理解doExecute這個(gè)方法的目的，必須通讀代碼，而我只是想知道它做了什么事；最后，這個(gè)方法如果某一行出問(wèn)題了，那么影響范圍是整個(gè)業(yè)務(wù)流程。

如果后期需要改動(dòng)，大部分人可能會(huì)增加條件判斷，或是在后面繼續(xù)追加代碼實(shí)現(xiàn)，最后會(huì)導(dǎo)致越來(lái)越難以閱讀，這其實(shí)也就是“能運(yùn)行就不要?jiǎng)铀边@個(gè)梗的根源了，因?yàn)闆](méi)人能讀明白它到底做了什么，但又不得不改，同時(shí)可能伴隨著“口吐芬芳”。

三、意識(shí)先行，從一行做起

那么到底該如何做呢？下面是我的一個(gè)例子：

public StepExitEnum doExecute(StepContext stepContext) throws Exception {
    initTempFilePath(stepContext);
    File[] encryptedFiles = findEncryptedFiles(stepContext);
    dencryptFiles(encryptedFiles, stepContext);
    return StepExitEnum.CONTINUING;
}

先不論具體實(shí)現(xiàn)細(xì)節(jié)，是不是一眼看過(guò)之后就了解doExecute做了什么事？這個(gè)方法的確沒(méi)有任何注釋?zhuān)欠裼绊戦喿x？其實(shí)我做的只是把先前的代碼重新歸類(lèi)，分別放到了三個(gè)方法中，核心實(shí)現(xiàn)還是原本的代碼，沒(méi)有改動(dòng)，現(xiàn)在閱讀起來(lái)是不是順暢了許多？

通讀代碼后我發(fā)現(xiàn)其實(shí)只做了三件事：創(chuàng)建目錄、讀取加密文件、解密文件，這是最核心的三個(gè)步驟，把它抽象出來(lái)，獨(dú)立為方法，既表達(dá)了邏輯功能，也清晰閱讀，還可以縮小影響范圍，今后哪里有問(wèn)題改哪里，不需要再通讀代碼了。

四、回到主題，再說(shuō)可讀性

（1）抽象，合理的業(yè)務(wù)邏輯抽象

“一個(gè)方法只應(yīng)該做一件事”，想必很多人聽(tīng)過(guò)類(lèi)似的表述，聽(tīng)起來(lái)簡(jiǎn)單做起來(lái)難，怎么定義“只做一件事”？這件事的邊界是什么？這就依賴(lài)coder對(duì)業(yè)務(wù)邏輯、對(duì)功能實(shí)現(xiàn)的深入理解和合理抽象，這才能清晰的區(qū)分出各個(gè)功能的邊界，或者說(shuō)是如何定義這件“事”。

沒(méi)有基于業(yè)務(wù)的合理抽象，硬生生地寫(xiě)了幾個(gè)方法，你會(huì)發(fā)現(xiàn)這幾個(gè)方法“藕斷絲連”，一個(gè)方法的參數(shù)變化總會(huì)影響到另一個(gè)方法，很難將一個(gè)方法單拎出來(lái)應(yīng)用在其他場(chǎng)景，一處改，處處改，這時(shí)候就要考慮，方法抽象的是否合理？

合理的抽象，從功能角色、職責(zé)劃分上就很清晰，有了這個(gè)基礎(chǔ)，才能清晰的編寫(xiě)業(yè)務(wù)邏輯代碼，而不是堆砌各種條件判斷和循環(huán)，同時(shí)帶著兩條斜杠和注釋?zhuān)@是可讀性的基礎(chǔ)。

（2）各司其職，職責(zé)單一

一個(gè)方法只做一件事，擴(kuò)展到一個(gè)類(lèi)也如此，職責(zé)單一，歸根結(jié)底還得基于合理的抽象，所以，它其實(shí)是抽象的一種具體體現(xiàn)，二者總是相輔相成。

（3）命名規(guī)范

這也是老生常談了，但真正做到的coder其實(shí)不多，類(lèi)名、方法、變量的命名規(guī)則其實(shí)很有講究，但這不是本文的主題，不多贅述，類(lèi)名用名詞，方法名用動(dòng)詞，因?yàn)轭?lèi)表述的是做什么事，而方法名表述的是如何做，規(guī)范的命名和正確的詞法，這是編碼的基礎(chǔ)功底，這會(huì)有助于他人閱讀代碼，當(dāng)然也是為什么我們讀spring源碼會(huì)感覺(jué)順暢，而讀同事寫(xiě)的業(yè)務(wù)代碼卻很蹩腳的原因，我們太過(guò)于強(qiáng)調(diào)spring的IOC了，卻忽略了最基礎(chǔ)的東西。

（4）關(guān)鍵注釋

注釋不能少，但也不應(yīng)該每個(gè)方法、每個(gè)判斷、每個(gè)循環(huán)到處都是//和/*，畢竟代碼是主體不是注釋?zhuān)疫@樣還會(huì)帶來(lái)隱性的工作量問(wèn)題：代碼修改，注釋也必須修改。所以好的注釋不是多，是關(guān)鍵。例如java.util.HashMap類(lèi)的注釋上會(huì)告訴你線程安全問(wèn)題：

Note that this implementation is not synchronized.

這是很關(guān)鍵的信息，所以注釋要給出關(guān)鍵性的、使用上注意的事項(xiàng)，不在于多。

代碼可讀性其實(shí)是一個(gè)比較寬泛的問(wèn)題，也是一個(gè)老生常談的問(wèn)題，隨著編碼經(jīng)驗(yàn)積累，在不同職業(yè)階段，我們對(duì)可讀性都會(huì)有不同的理解和認(rèn)識(shí)，本文從我自己的角度和經(jīng)驗(yàn)，討論了一些比較淺的理解，如何寫(xiě)出易讀、易懂的優(yōu)秀代碼，可能是我們coder永遠(yuǎn)追尋的目標(biāo)之一，即使它沒(méi)有終點(diǎn)。

?

最后別忘了“一鍵三連”！


審核編輯 黃宇