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

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

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

設計“深”的類

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

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

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

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

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

FileInputStream fileStream = new FileInputStream(fileName);

BufferedInputStream bufferedStream = new BufferedInputStream(fileStream);

ObjectInputStream objectStream = new ObjectInputStream(bufferedStream);

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

好好寫注釋

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

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

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

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

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

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

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

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

能夠將設計時想到的東西記錄下來，而且方便后續維護

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

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

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

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

注意事項

《軟件設計哲學》中還提到了一些在開發中需要謹慎注意的事情：

盡可能少用配置參數

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

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

指定默認值：當某些參數不被配置時，提供默認值來滿足基本的功能

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

保持一致性

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

尋求通用的設計

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

滿足當前需求最簡單的接口是什么？

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

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

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

終：沒有孰是孰非

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

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

That's all.

審核編輯 黃宇