第 15 章 先寫註解

（把註解變成設計過程的一部分）

許多開發人員把編寫文件推遲到開發的最後階段，等編碼和單元測試完成後再寫。這是最容易產生低品質文件的做法之一。編寫註解的最佳時機是開發之初，就在編寫程式碼的時候。先寫註解，就能讓文件成為設計過程的一部分。這不僅能帶來更好的文件和設計，也能讓編寫文件的過程更愉快。

本章概覽註解應該在什麼時候寫？

15.1 遲到的註解不是好註解

我見過的開發人員幾乎都會推遲寫註解。問起為什麼不早點寫文件，他們會說程式碼還在變：如果現在就寫，程式碼變更時還得重寫，不如等程式碼穩定下來再說。但我懷疑還有另一個原因：他們把寫文件當作苦差事，所以能拖就拖。

這種做法有幾個不良後果。首先，推遲寫文件往往意味著最後根本不會寫。一旦開始拖延，就很容易再拖一陣，畢竟過幾周代碼還會更穩定。等程式碼真正穩定下來，已經積累了大量程式碼，補寫文件的任務也變得更龐大、更讓人不願著手。似乎總找不到合適的時間停下幾天，把缺失的註解補齊。人們也很容易為拖延找到理由：對專案來說，繼續迭代、修復缺陷或開發下一個功能才更重要。結果，沒有註解的程式碼越來越多。

即使你有足夠的自制力回頭補註解（別自欺欺人，你很可能並沒有），也很難寫好。此時，你的心思已經不在這裡：你覺得程式碼已經完成，急著開始下一個專案。你知道應該寫註解，卻覺得毫無樂趣，只想儘快了事。於是，你匆匆瀏覽程式碼，補上一些註解，看起來差不多就行。距離設計這段程式碼已經過去一段時間，設計過程的記憶也模糊了。對著程式碼補註解，很容易只是在重複程式碼。即使努力回想那些無法直接從程式碼看出的設計思路，也難免有所遺忘，結果遺漏了註解本該說明的一些最重要的資訊。

譯者圖解推遲註解，為什麼可能越積越難補？

15.2 先寫註解

我的做法不同：從一開始就寫註解。

• 對於新類，我首先編寫類介面註解。
• 接下來，我為最重要的公有方法編寫介面註解和簽名，但將方法主體保留為空。
• 我反覆修改這些註解，直到覺得基本結構合理為止。
• 然後，為類中最重要的實例變數編寫宣告和註解。
• 最後，編寫方法體，並根據需要新增實作註解。
• 編寫方法體時，通常會發現還需要更多方法和實例變數。對於每個新方法，我都先寫介面註解，再寫方法體；對於每個實例變數，則在寫宣告時一併寫好註解。

這樣，程式碼完成時，註解也已經完成，不會積壓待補寫的註解。

先寫註解有三個好處。首先，註解的品質更好。設計類時，關鍵設計問題正清楚地留在腦中，很容易記錄下來。最好在編寫每個方法體之前先寫介面註解，這樣就能專注於方法的抽象和介面，不被實作細節分散注意力。在後續編碼和測試中，還會發現並修正註解中的問題，使註解隨著開發持續改進。

譯者圖解先寫註解不是寫完就凍結

15.3 註解是一種設計工具

先寫註解的第二個、也是最重要的好處，是改善系統設計。註解是完整描述抽象的唯一方式，而好的抽象是良好系統設計的基礎。如果一開始就寫好描述抽象的註解，就能在編寫實作程式碼之前檢查和調整抽象。要寫好註解，必須認清變數或程式碼的本質：其中最重要的是什麼？在設計早期想清楚這一點很重要，否則就只是埋頭寫程式碼。

註解就像煤礦中的金絲雀，可以預警複雜性。如果方法或變數需要很長的註解，這就是一個危險訊號，表明抽象不夠好。請記住第 4 章的原則，類應該是深的：最好的類介面非常簡單，卻能提供強大的功能。判斷介面複雜性的最佳方法，是查看描述介面的註解。如果介面註解簡短、簡單，又包含使用該方法所需的全部資訊，就說明介面很簡單。反之，如果必須用冗長、複雜的註解才能完整描述一個方法，就說明介面很複雜。將方法的介面註解與實作相比較，還能判斷方法有多深：如果介面註解必須描述實作的所有主要特性，這個方法就是淺的。變數也是如此：如果必須用很長的註解才能完整描述變數，就是一個危險訊號，表明變數可能沒有得到合理拆分。總之，寫註解能讓你及早評估設計決策，發現並解決問題。

危險訊號：難以描述

描述方法或變數的註解應該簡單而完整。如果你發現很難寫這樣的註解，則表明你對所描述事物的設計可能存在問題。

當然，只有完整、清晰的註解，才能有效反映複雜性。如果方法的介面註解遺漏了呼叫所需的資訊，或者本身就晦澀難懂，也就無法據此準確判斷方法的深度。

譯者圖解刪掉呼叫條件，不會刪掉呼叫義務

15.4 先寫註解很有趣

儘早寫註解的第三個、也是最後一個好處，是讓這項工作更有趣。對我來說，程式設計最有趣的部分之一就是新類的早期設計，在這個階段逐步完善類的抽象和結構。我的大部分註解都寫於此時，用來記錄設計決策，並檢驗其品質。我會尋找能用盡量少的文字完整、清晰地表達的設計。註解越簡單，我對設計就越滿意，寫出簡明的註解也會帶來成就感。如果你採用戰略式程式設計，把出色的設計而不只是能工作的程式碼作為主要目標，那麼寫註解應該是有趣的，因為它能幫助你找到最佳設計。

15.5 先寫註解是否很昂貴？

現在，重新審視推遲寫註解的理由：可以省去程式碼演變時修改註解的成本。粗略估算就能看出，這樣節省不了多少時間。先估算實際鍵入程式碼和註解所佔的開發時間比例，包括修改程式碼和註解的時間；它不太可能超過全部開發時間的約 10%。即使全部程式碼行中有一半是註解，寫註解佔用的時間也很可能不超過開發總時間的約 5%。把註解拖到最後，只能節省其中很小的一部分。

先寫註解則意味著，在動手寫程式碼之前，抽象已經更加穩定，這很可能節省編碼時間。反過來，如果先寫程式碼，抽象很可能隨編碼過程而變化，需要的程式碼修改也會比先寫註解時更多。綜合這些因素，先寫註解可能反而更省時間。

15.6 結論

如果你從未試過先寫註解，不妨試一試，並堅持到習慣這種做法。然後想一想，它對註解品質、設計品質以及軟體開發的整體樂趣有什麼影響。嘗試一段時間後，請告訴我你的體驗是否與我的一致，以及其中的原因。

本章回顧從拖到最後補的註解，到用註解檢驗設計