目錄

• 15.1 延遲的註釋是糟糕的註釋
• 15.2 先寫註釋
• 15.3 註釋是一個設計工具
• 15.4 早期的註釋很有趣
• 15.5 早期的註釋代價高昂嗎?
• 15.6 結論

許多開發人員將編寫文件的工作推遲到開發過程的末尾，即編碼和單元測試完成之後。這是產生低質量文件的最可靠的方法之一。編寫註釋的最佳時間是在過程的開始，即編寫程式碼的時候。 首先編寫註釋使文件成為設計過程的一部分。這不僅產生了更好的文件，而且還產生了更好的設計，並使編寫文件的過程更加愉快。

15.1 延遲的註釋是糟糕的註釋

我遇到的幾乎所有開發人員都推遲了寫註釋的時間。當被問及為什麼不更早地編寫文件時，他們說程式碼仍然在變化。他們說，如果他們很早就編寫文件，那麼當代碼發生變化時，他們就必須重寫文件；最好等到程式碼穩定下來。然而，我懷疑還有另一個原因，那就是他們把文件看作是苦力工作；因此，他們儘可能地拖延。

不幸的是，這種方法有幾個負面的後果。首先，延遲文件通常意味著根本不需要編寫文件。一旦你開始拖延，很容易再拖延一點;畢竟，再過幾周，程式碼將更加穩定。等到程式碼穩定下來的時候，已經有很多了，這意味著編寫文件的任務已經變得非常艱鉅，甚至沒有吸引力了。從來沒有合適的時間停下來幾天，把所有遺漏的註釋都補上，而且很容易讓人覺得對專案來說最好的事情就是繼續前進，修復bug或者編寫下一個新特性。這將建立更多未歸檔的程式碼。

即使你有自律性回去寫註釋(不要欺騙你自己：你可能沒有)，註釋也不會很好。在這個過程的這個時候，你已經在精神上離開了。在你的腦海裡，這段程式碼已經完成了;你急於開始下一個專案。你知道寫註釋是正確的事情，但它沒有樂趣。你只想儘快度過難關。因此，您可以快速地瀏覽程式碼，新增足夠的註釋以使其看起來令人滿意。到目前為止，您已經有一段時間沒有設計程式碼了，所以您對設計過程的記憶變得模糊了。您在編寫註釋時檢視程式碼，因此註釋重複了程式碼。即使您試圖重構程式碼中不明顯的設計思想，也會有您不記得的事情。因此，這些註釋忽略了他們應該描述的一些最重要的事情。

15.2 先寫註釋

我用了一種不同的方法來寫註釋，我把註釋寫在最開始：

1. 對於一個新類，我首先編寫類介面註釋。
2. 接下來，我為最重要的公共方法編寫介面註釋和簽名，但方法主體為空。
3. 我對這些註釋進行了一些迭代，直到基本結構感覺正確為止。
4. 此時，我為類中最重要的類例項變數編寫宣告和註釋。
5. 最後，我填寫方法的主體，根據需要新增實現註釋。
6. 在編寫方法主體時，我通常會發現需要額外的方法和例項變數。對於每個新方法，我都在方法體之前寫介面註釋;對於例項變數，我在編寫變數宣告的同時填寫註釋。

程式碼完成後，註釋也完成了。從來沒有積壓的不成文的註釋。

先註釋的方法有三個好處：

• 首先，它產生了更好的註釋。如果您在設計類時寫下注釋，那麼關鍵的設計問題就會在您的腦海中浮現出來，所以很容易記錄下來。
• 最好在每個方法的主體之前編寫介面註釋，這樣您就可以專注於方法的抽象和介面，而不會被實現分散注意力。
• 在編碼和測試過程中，您將注意到並修復註釋中的問題。因此，註釋在發展的過程中不斷改進。

15.3 註釋是一個設計工具

在開始時編寫註釋的第二個好處(也是最重要的一個好處)是改進了系統設計。註釋提供了完全捕獲抽象的唯一方法，好的抽象是好的系統設計的基礎。如果您在開始時編寫了描述抽象的註釋，那麼您可以在編寫實現程式碼之前對它們進行檢查和調優。要寫出好的註釋，您必須識別一個變數或一段程式碼的本質：這個東西最重要的方面是什麼？在設計過程的早期就這樣做是很重要的，否則你只是在破解程式碼。

註釋就像是複雜煤礦中的金絲雀。如果一個方法或變數需要很長的註釋，這是一個警告，說明您沒有一個好的抽象。請記住，在第4章中，類應該是深入的：最好的類具有非常簡單的介面，但是實現了強大的功能。判斷介面複雜性的最佳方法是根據描述它的註釋。如果方法的介面註釋提供了使用該方法所需的所有資訊，並且很短很簡單，則表明該方法具有簡單的interface。相反，如果沒有長而複雜的註釋就無法完整地描述一個方法，那麼這個方法就有一個複雜的介面。您可以將方法的介面註釋與實現進行比較，以瞭解該方法的深度：如果介面註釋必須描述實現的所有主要特性，則該方法是膚淺的。同樣的思想也適用於變數：如果需要很長的註釋才能完整地描述一個變數，這是一個危險訊號，表明您可能沒有選擇正確的變數分解。總的來說，編寫註釋的行為允許您儘早評估您的設計決策，這樣您就可以發現並修復問題。

危險訊號：難以描述

描述方法或變數的註釋應該簡單而完整。如果你發現很難寫這樣的註釋，那就說明你所描述的東西的設計可能有問題。

當然，註釋只有在完整和清晰的情況下才能很好地指示覆雜性。如果您編寫的方法介面註釋沒有提供呼叫該方法所需的所有資訊，或者註釋非常晦澀，難以理解，那麼該註釋就不能很好地度量方法的深度。

15.4 早期的註釋很有趣

儘早寫註釋的第三個也是最後一個好處是，它讓註釋寫作變得更有趣。對我來說，程式設計中最有趣的部分之一是新類的早期設計階段，在這個階段，我將充實類的抽象和結構。我的大多數註釋都是在這個階段寫的，這些註釋是我如何記錄和測試我的設計決策的質量的。我正在尋找的設計，可以表達完整和明確的最少的語言。註釋越簡單，我對我的設計就感覺越好，所以找到簡單的註釋是我的驕傲。如果你是有策略地進行程式設計，你的主要目標是一個偉大的設計，而不是僅僅編寫可以工作的程式碼，那麼編寫註釋應該是有趣的，因為這是你識別最佳設計的方式。

15.5 早期的註釋代價高昂嗎?

現在，讓我們重新討論延遲註釋的理由，即它避免了隨著程式碼的發展而重新處理註釋的成本。一個簡單的粗略計算將表明，這並沒有節省多少。首先，估計您在一起輸入程式碼和註釋所花費的開發時間，包括修改程式碼和註釋的時間;這不太可能超過所有開發時間的10%。即使您的程式碼行總數的一半是註釋，編寫註釋也不會佔用您全部開發時間的5%。把註釋拖到最後只會節省其中的一小部分，並不是很多。

首先編寫註釋將意味著在開始編寫程式碼之前抽象將更加穩定。這可能會節省編碼期間的時間。相反，如果您先編寫程式碼，抽象可能會隨著您的程式碼而發展，這將比先註釋的方法需要更多的程式碼修訂。當您考慮到所有這些因素時，首先編寫註釋可能會更快。

15.6 結論

如果你還沒有嘗試過先寫註釋，那就試試吧。堅持到習慣為止。然後考慮它如何影響您的註釋質量、設計質量和軟體開發的整體享受。在你嘗試了一段時間後，讓我知道你的經驗是否與我的相匹配，為什麼或為什麼不。