工作三年以來一直對寫出設(shè)計優(yōu)雅且可讀性較好的代碼抱有執(zhí)念，最初接觸到的關(guān)于代碼整潔和軟件設(shè)計的書是《代碼整潔之道》，這本書大概在我入職半年時讀完，并在很長的一段時間內(nèi)將其中談到的“每個方法只做一件事”、“方法長度最多不要超過 5 行”和“優(yōu)秀的代碼都是自解釋的，很少會有注釋”等等觀點奉為圭臬，但是由于其成書較早，其中的一些觀點顯然已經(jīng)不再使用當(dāng)前業(yè)務(wù)開發(fā)環(huán)境了。就拿前兩點來說，看上去能讓每個小方法盡可能的簡單，但是對于復(fù)雜的業(yè)務(wù)系統(tǒng)來說，這將會產(chǎn)生很多的小方法堆疊，產(chǎn)生“方法風(fēng)暴”，在看一個方法時，需要不斷的在各個小方法中往復(fù)跳轉(zhuǎn)，使得可讀性大大降低。

然而，《軟件設(shè)計哲學(xué) A Philosophy of Software Design》我覺得相對來說是更符合當(dāng)前軟件開發(fā)的指導(dǎo)書，其中談到了與其相反的觀點：“方法的可讀性并不取決于它的長度”，“隔離復(fù)雜性，設(shè)計深的模塊”和“寫完善的注釋內(nèi)容”等等，我認為這些和我們當(dāng)前的開發(fā)是相契合的，以其中的原則作為開發(fā)設(shè)計指南也是非常合適的。

本文則主要是對其中談到的部分觀點進行討論，深入學(xué)習(xí)還是推薦大家去看原書。

設(shè)計“深”的類

設(shè)計較好的類通常功能強大但是公開出的接口非常簡單，這樣的類被稱為“深”的。什么是“深”的類呢？如下圖所示：

如果用矩形來表示類的話，則矩形的面積與類提供的功能成正比；矩形頂部邊緣表示類公開出的接口，邊緣長度越長則表示接口越復(fù)雜。較“深”的類，因為其內(nèi)部復(fù)雜性只有很小一部分對調(diào)用者可見，所以稱它設(shè)計較好。

以 Java 語言中的垃圾回收器為例，它在后臺操作垃圾回收，實現(xiàn)非常復(fù)雜，而這種復(fù)雜性對程序員卻是隱藏的，因為它根本沒有公開出任何接口。

不過，在《代碼整潔之道》中，深類的價值并沒有得到肯定，而且在軟件設(shè)計的傳統(tǒng)觀點中也認為：“類應(yīng)該小，而不是深”，一些較大的類通常會被鼓勵拆分成多個小類。這種設(shè)計原則會導(dǎo)致創(chuàng)建大量的淺類（每個類都很簡單），在《軟件設(shè)計哲學(xué)》中被稱為“多類癥”，是一種冗長的編碼風(fēng)格。這些淺類都具有自己的接口，但并不會貢獻太多的功能，隨著這些淺類的累積，系統(tǒng)的復(fù)雜性會隨之增加。

Java IO 類庫是“多類癥”很好的例子，比如我們要在文件中獲取序列化的對象，要寫如下代碼：

FileInputStream fileStream = new FileInputStream(fileName);

BufferedInputStream bufferedStream = new BufferedInputStream(fileStream);

ObjectInputStream objectStream = new ObjectInputStream(bufferedStream);

我們必須創(chuàng)建 3 個對象來完成這個操作，前兩個步驟中 FileInputStream 提供基本的 I/O，BufferedInputStream 添加執(zhí)行緩沖的功能，而實際上我們想要的只是最后創(chuàng)建的 ObjectInputStream 對象，這使編碼看上去比較冗余。盡管這使得各個類的職責(zé)更加分明，并且允許用戶創(chuàng)建不帶有緩存機制的序列化對象，但這并沒有帶來簡單易用的結(jié)果。提供選擇固然是好的，但如果沒有因此使其簡單易用則背離了設(shè)計的初衷。

好好寫注釋

花時間來好好為變量和方法命名，是非常值得的，它能大大的提高可讀性，最好的情況是：當(dāng)讀者看到它時，就已經(jīng)基本領(lǐng)會了它的作用。盡可能的讓它們明確、直觀且不太長。如果很難為變量或方法找到一個簡單的名稱，那么這可能暗示底層對象的設(shè)計不夠簡潔，可以考慮拆分成多個分別定義或者為其添加上必要的注釋。

但《代碼整潔之道》中卻對注釋持有消極的觀點：

... 注釋最多只能算是一種不得已而為之的手段。若編程語言有足夠的表達力，或者我們長于用這些語言來表達意圖，就不那么需要注釋——也許根本不需要。

注釋的恰當(dāng)用法是彌補我們在代碼中未能表達清楚的內(nèi)容... 注釋總是代表著失敗，我們總有不用注釋便很難表達代碼意圖的時候，所以總要有注釋，這并不值得慶賀。

曾經(jīng)我也對這個觀點信以為然，但是隨著我在開發(fā)中盡力寫自解釋的代碼時卻發(fā)現(xiàn)：緊靠幾個簡短的詞語并不能將方法的作用解釋清楚，想讓它自解釋就會導(dǎo)致方法名寫的很長，而且多數(shù)情況下，研發(fā)同事并不愿意花精力去翻譯那冗長又蹩腳的方法名，給人更多的感受是：“這寫的都是什么？”

后來，我漸漸放棄了寫自解釋的代碼，并通過添加注釋來增加可讀性，這不僅僅減少了大家對代碼提出的抱怨，而且還減輕了為方法命名的壓力。“好的代碼是自解釋的”的觀點也在心中祛魅，它其實更像是程序員心中的美好幻想。

注釋除了能提高可讀性之外，還能隱藏復(fù)雜性，提高抽象程度。它能對接口實現(xiàn)進行概括，相當(dāng)于是實現(xiàn)的簡化視圖，如果讀者必須要去接口實現(xiàn)中研究每一段代碼才能了解它的功能的話，那么就談不上任何抽象了。

還有一點值得注意的是：注釋并不是彌補方法名表達能力欠佳的補丁，也不是簡單的對代碼的重復(fù)，而是代碼書寫前的先決條件。因為先寫注釋能帶來很多好處：

能夠?qū)⒃O(shè)計時想到的東西記錄下來，而且方便后續(xù)維護

先寫注釋能更在開發(fā)進行時衡量設(shè)計，如果方法或變量的注釋能夠以非常簡潔的描述來概括它的功能，那么通常設(shè)計是較好的，如果注釋非常冗長，而且其中暴露出很多具體實現(xiàn)相關(guān)的內(nèi)容，那么設(shè)計可能需要重新考慮

如果你崇尚良好設(shè)計的話，那么寫注釋是一件有意思的事情，因為你會發(fā)現(xiàn)，你的設(shè)計是如此的簡潔，以至于你只需要寫一兩句話就能描述清楚它的功能

如果使用 AI 代碼自動補全功能的話，你將能更強烈地感受到它的威力

隨著注釋寫的越來越多，你會發(fā)現(xiàn)：注釋其實是代碼的一部分，因為它不光提供代碼之外的重要信息，還反映了開發(fā)者對代碼的設(shè)計和重視，隨著時間的推移，有新的開發(fā)者加入時，也能讓他快速理解代碼，降低出現(xiàn) Bug 的概率。

注意事項

《軟件設(shè)計哲學(xué)》中還提到了一些在開發(fā)中需要謹慎注意的事情：

盡可能少用配置參數(shù)

這個觀點讓我想到在開發(fā)補購查詢接口時為其添加的配置，其中可對查詢的數(shù)據(jù)規(guī)模和相關(guān)品類信息等進行配置。雖然該配置僅供研發(fā)使用，但是實際上這提高了接口的復(fù)雜性。為了將其帶來的復(fù)雜性降到最低，采用了以下兩種方法：

詳細的注釋：為配置類中的每個字段添加上詳細的注釋，讓研發(fā)能清晰的了解每個參數(shù)的作用

指定默認值：當(dāng)某些參數(shù)不被配置時，提供默認值來滿足基本的功能

自適應(yīng)變更配置是書中提到的一個不錯的觀點，通過代碼的執(zhí)行情況不斷自適應(yīng)調(diào)整參數(shù)值，減少人為的干預(yù)，但是我認為這種方法應(yīng)用的場景比較有限，它更像是算法中參數(shù)的自適應(yīng)調(diào)整。

保持一致性

有些項目可能開發(fā)較早，并沒有隨著軟件設(shè)計的發(fā)展而實時調(diào)整，但這并不能算得上是什么壞事，只要大家在項目中遵循現(xiàn)有約定，也能維持較好的系統(tǒng)設(shè)計。反倒說貿(mào)然地引入新的設(shè)計原則，造成新原則和舊原則并存才是更糟糕的，因為這很可能會導(dǎo)致混亂。

尋求通用的設(shè)計

在開發(fā)需求時，盡可能不進行定制化開發(fā)，而是思考通用的實現(xiàn)邏輯，即使在不考慮復(fù)用的情況下，通用性代碼也是更合理的。在進行開發(fā)設(shè)計時，可以嘗試思考如下問題來引導(dǎo)自己找出通用設(shè)計：

滿足當(dāng)前需求最簡單的接口是什么？

這個方法會在多少種情況下被使用？

目前通用的 API 使用起來是否簡單？

不管是專用的類或方法還是代碼里的特殊情況，都是軟件復(fù)雜性的主要來源。專用代碼無法完全消除，但通過良好的設(shè)計能夠顯著減少專用代碼，并將專用代碼與通用代碼分開。這能使類更深、隱藏復(fù)雜性以及讓代碼更簡單、更清晰。

終：沒有孰是孰非

我覺得《軟件設(shè)計哲學(xué)》是站在代碼閱讀者的角度上，考慮的是該如何設(shè)計能讓讀者更輕松的讀懂，降低復(fù)雜性，像其中的提到的“永遠不要反駁他人對代碼可讀性的評價”的觀點，都是在對其進行強調(diào)。而《代碼整潔之道》給我的感受是站在代碼的書寫者身上，因為我覺得像“一個方法只做一件事”、“代碼長度不要超過多少行”和“盡可能不寫注釋”等原則，更多的是強調(diào)如何寫，或者說是讓研發(fā)人員關(guān)注如何寫上，對于如何讓讀者讀懂，是沒有深入去考慮的。當(dāng)然《代碼整潔之道》也并不是一無是處，比如其中談到：“方法的排列要自上而下，讓讀者看起來就像讀報紙一樣，并不是簡單的將公有或私有方法排列在一起”，這對代碼的可讀性也是有幫助的。所以，這兩本書更適合結(jié)合起來比較閱讀。

更重要的是，《軟件設(shè)計哲學(xué)》強調(diào)要成為一名軟件設(shè)計師，并不斷提高設(shè)計技能，降低系統(tǒng)的復(fù)雜性。雖然這可能會將大部分時間花在設(shè)計上，但是這些設(shè)計會很快帶來回報，尤其是需要對這部分功能一遍又一遍地迭代時，你一定會發(fā)出“幸虧做了良好設(shè)計”的感嘆，并從中獲得源源不斷的快樂。

That's all.

審核編輯 黃宇