許多開發人員將編寫文檔的工作推遲到開發過程的末尾，即編碼和單元測試完成之后。這是產生低質量文檔的最可靠的方法之一。編寫注釋的最佳時間是在過程的開始，即編寫代碼的時候。 首先編寫注釋使文檔成為設計過程的一部分。這不僅產生了更好的文檔，而且還產生了更好的設計，並使編寫文檔的過程更加愉快。
15.1 延遲的注釋是糟糕的注釋
我遇到的幾乎所有開發人員都推遲了寫注釋的時間。當被問及為什么不更早地編寫文檔時，他們說代碼仍然在變化。他們說，如果他們很早就編寫文檔，那么當代碼發生變化時，他們就必須重寫文檔；最好等到代碼穩定下來。然而，我懷疑還有另一個原因，那就是他們把文檔看作是苦力工作；因此，他們盡可能地拖延。
不幸的是，這種方法有幾個負面的后果。首先，延遲文檔通常意味着根本不需要編寫文檔。一旦你開始拖延，很容易再拖延一點;畢竟，再過幾周，代碼將更加穩定。等到代碼穩定下來的時候，已經有很多了，這意味着編寫文檔的任務已經變得非常艱巨，甚至沒有吸引力了。從來沒有合適的時間停下來幾天，把所有遺漏的注釋都補上，而且很容易讓人覺得對項目來說最好的事情就是繼續前進，修復bug或者編寫下一個新特性。這將創建更多未歸檔的代碼。
即使你有自律性回去寫注釋(不要欺騙你自己：你可能沒有)，注釋也不會很好。在這個過程的這個時候，你已經在精神上離開了。在你的腦海里，這段代碼已經完成了;你急於開始下一個項目。你知道寫注釋是正確的事情，但它沒有樂趣。你只想盡快度過難關。因此，您可以快速地瀏覽代碼，添加足夠的注釋以使其看起來令人滿意。到目前為止，您已經有一段時間沒有設計代碼了，所以您對設計過程的記憶變得模糊了。您在編寫注釋時查看代碼，因此注釋重復了代碼。即使您試圖重構代碼中不明顯的設計思想，也會有您不記得的事情。因此，這些注釋忽略了他們應該描述的一些最重要的事情。
15.2 先寫注釋
我用了一種不同的方法來寫注釋，我把注釋寫在最開始：
- 對於一個新類，我首先編寫類接口注釋。
- 接下來，我為最重要的公共方法編寫接口注釋和簽名，但方法主體為空。
- 我對這些注釋進行了一些迭代，直到基本結構感覺正確為止。
- 此時，我為類中最重要的類實例變量編寫聲明和注釋。
- 最后，我填寫方法的主體，根據需要添加實現注釋。
- 在編寫方法主體時，我通常會發現需要額外的方法和實例變量。對於每個新方法，我都在方法體之前寫接口注釋;對於實例變量，我在編寫變量聲明的同時填寫注釋。
代碼完成后，注釋也完成了。從來沒有積壓的不成文的注釋。
先注釋的方法有三個好處：
- 首先，它產生了更好的注釋。如果您在設計類時寫下注釋，那么關鍵的設計問題就會在您的腦海中浮現出來，所以很容易記錄下來。
- 最好在每個方法的主體之前編寫接口注釋，這樣您就可以專注於方法的抽象和接口，而不會被實現分散注意力。
- 在編碼和測試過程中，您將注意到並修復注釋中的問題。因此，注釋在發展的過程中不斷改進。
15.3 注釋是一個設計工具
在開始時編寫注釋的第二個好處(也是最重要的一個好處)是改進了系統設計。注釋提供了完全捕獲抽象的唯一方法，好的抽象是好的系統設計的基礎。如果您在開始時編寫了描述抽象的注釋，那么您可以在編寫實現代碼之前對它們進行檢查和調優。要寫出好的注釋，您必須識別一個變量或一段代碼的本質：這個東西最重要的方面是什么？在設計過程的早期就這樣做是很重要的，否則你只是在破解代碼。
注釋就像是復雜煤礦中的金絲雀。如果一個方法或變量需要很長的注釋，這是一個警告，說明您沒有一個好的抽象。請記住，在第4章中，類應該是深入的：最好的類具有非常簡單的接口，但是實現了強大的功能。判斷接口復雜性的最佳方法是根據描述它的注釋。如果方法的接口注釋提供了使用該方法所需的所有信息，並且很短很簡單，則表明該方法具有簡單的interface。相反，如果沒有長而復雜的注釋就無法完整地描述一個方法，那么這個方法就有一個復雜的接口。您可以將方法的接口注釋與實現進行比較，以了解該方法的深度：如果接口注釋必須描述實現的所有主要特性，則該方法是膚淺的。同樣的思想也適用於變量：如果需要很長的注釋才能完整地描述一個變量，這是一個危險信號，表明您可能沒有選擇正確的變量分解。總的來說，編寫注釋的行為允許您盡早評估您的設計決策，這樣您就可以發現並修復問題。
危險信號：難以描述
描述方法或變量的注釋應該簡單而完整。如果你發現很難寫這樣的注釋，那就說明你所描述的東西的設計可能有問題。
當然，注釋只有在完整和清晰的情況下才能很好地指示復雜性。如果您編寫的方法接口注釋沒有提供調用該方法所需的所有信息，或者注釋非常晦澀，難以理解，那么該注釋就不能很好地度量方法的深度。
15.4 早期的注釋很有趣
盡早寫注釋的第三個也是最后一個好處是，它讓注釋寫作變得更有趣。對我來說，編程中最有趣的部分之一是新類的早期設計階段，在這個階段，我將充實類的抽象和結構。我的大多數注釋都是在這個階段寫的，這些注釋是我如何記錄和測試我的設計決策的質量的。我正在尋找的設計，可以表達完整和明確的最少的語言。注釋越簡單，我對我的設計就感覺越好，所以找到簡單的注釋是我的驕傲。如果你是有策略地進行編程，你的主要目標是一個偉大的設計，而不是僅僅編寫可以工作的代碼，那么編寫注釋應該是有趣的，因為這是你識別最佳設計的方式。
15.5 早期的注釋代價高昂嗎?
現在，讓我們重新討論延遲注釋的理由，即它避免了隨着代碼的發展而重新處理注釋的成本。一個簡單的粗略計算將表明，這並沒有節省多少。首先，估計您在一起輸入代碼和注釋所花費的開發時間，包括修改代碼和注釋的時間;這不太可能超過所有開發時間的10%。即使您的代碼行總數的一半是注釋，編寫注釋也不會占用您全部開發時間的5%。把注釋拖到最后只會節省其中的一小部分，並不是很多。
首先編寫注釋將意味着在開始編寫代碼之前抽象將更加穩定。這可能會節省編碼期間的時間。相反，如果您先編寫代碼，抽象可能會隨着您的代碼而發展，這將比先注釋的方法需要更多的代碼修訂。當您考慮到所有這些因素時，首先編寫注釋可能會更快。
15.6 結論
如果你還沒有嘗試過先寫注釋，那就試試吧。堅持到習慣為止。然后考慮它如何影響您的注釋質量、設計質量和軟件開發的整體享受。在你嘗試了一段時間后，讓我知道你的經驗是否與我的相匹配，為什么或為什么不。