評論總是錯的 - 對，還是不對？

Question

隨機運行這個blog關於如何不應該讀取評論，並認爲我讀過的所有評論都是錯誤的，過時的或者簡單的混淆。如果一個簡單的從不閱讀評論和/或只是使用正則表達式替換模式刪除... :-) ...只是開玩笑，但真的，也許不是。至少看起來像評論和相關的代碼應該有時間戳。同意，還是不同意？

僅供參考，博客似乎是這個計算器的用戶：Nosredna

Answer 1

不準確的評論與錯誤代碼一樣嚴重。如果這是一個持續存在的問題，我會說這個項目存在嚴重問題。諸如PostgreSQL（src目錄中未壓縮的94M）等大型項目依賴準確的評論來幫助程序員快速理解事物。他們也非常認真地評論。

編輯：

另外，如果你不能總結一下你的函數是做，那麼誰可以？寫完一個函數後，編寫它的註釋可以是一個測試，你完全理解正在發生的事情。如果你的想法仍然有點混亂，當你嘗試寫評論時，它會變得非常明顯。這是一件好事，它顯示了還需要繼續努力。

Answer 2

一些意見是有用的，良好的，其他意見都沒有。

是的，評論和代碼應該是時間戳，但你不應該自己打印時間戳。您的源代碼管理系統應該爲您管理，並且您應該能夠訪問此信息（例如，使用cvs annotate或svn blame）。

Answer 3

代碼註釋有時可能是非常寶貴的。很多時候我一直在努力確定代碼的意圖不成功。對於任何複雜的代碼，如果作者記錄他們的意圖可能會有所幫助。當然，寫得很好的單元測試也可以使意圖清晰。

Answer 4

在現實世界中，編程不僅僅意味着編寫代碼。這意味着編寫另一位程序員（或者你自己，在3個月內）可以有效理解和維護的代碼。

任何程序員誰告訴你的意見/文檔是不值得花費的寫/維持他們的時候有一些問題：

• 他長期的工作速度（和任何同事誰必須與他的代碼一起工作）將低於它可能的。人們將浪費了大量的時間理解代碼，可以用簡短的句子來描述。

• 與他的代碼相關的錯誤率將高於他們的可能性，因爲所有他忘記提及的假設和特殊情況都會不斷提醒人們。 （你有多少次需要在你的代碼中做一些「不尋常」的事情來完成某些工作，忘記發表評論以說明你爲什麼這麼做了，然後再認爲它看起來像一個bug並「修復」它，只是發現你已經破壞了可怕的東西，因爲你不記得那麼微妙？）

• 如果他懶得寫下他的代碼是如何工作或應該被使用的，他還有什麼其他的快捷方式？他是否打算檢查空值並處理異常？他關心他的界面是否一致？如果它的基本含義發生變化，他會不會重構方法/變量的名稱？通常糟糕的評論只是冰山一角。

• 許多這樣的程序員過於關注「酷炫的東西」（比如優化代碼中的每一個最後一個循環，或者找到一種巧妙的方法來將看似簡單的代碼混淆成一個令人難以置信的模板）來理解商業現實（例如，他可能無法讓他的代碼工作並運到截止日期，因爲他專注於榨取不必要的性能而不是完成工作）

• 他的設計有多好？當我寫下文檔/評論時，我會完成大部分設計和思考。通過向讀者解釋我的評論，我清除了許多我會錯過的缺陷和假設。我甚至會說，我通常會寫評論（我的意圖/設計），然後與他們同步代碼。在大多數情況下，如果我的代碼中存在錯誤，那麼代碼是錯誤的而不是註釋。他還沒有意識到，通過使用良好的變量命名，精心設計的命名前綴/約定和文檔註釋，他可以更好地利用他的IDE的精彩時間節省功能（自動完成，智能感知幫助，等等），代碼更快，缺陷率更低。

從根本上說，他可能不知道如何寫出好的評論：

1）評論應的代碼塊的快速閱讀總結行動。我可以閱讀一行簡短的文本，而不必制定許多代碼行的含義。如果您發現自己正在閱讀代碼來瀏覽它，則它的評論很差。我閱讀這些評論來瀏覽和理解代碼，而當我真正需要處理它的特定位時，我只能閱讀代碼本身。

2）方法/類註釋應向調用者描述使用該類的所有知識，而不必查看代碼實現的「黑盒子」。他們將能夠快速掌握如何使用類/方法，並理解API提供的所有副作用和「契約」 - 可以爲null，必須提供什麼，以及拋出哪些異常等。如果你必須閱讀代碼才能得到它，那麼要麼封裝得很糟，要麼沒有很好的文檔。

3）使用像我的AtomineerUtils插件或子域的GhostDoc這樣的工具，這意味着他的文檔註釋可以保持與代碼同步，只需很少的努力。

Answer 5

個人而言，我不寫了一大堆的評論，但常見的類型的評論我做的寫有：

• （草圖）證明，我的代碼是正確的
• 解釋爲什麼不只是做明顯的事情（例如，g：需要優化，我打電話的API令人震驚地誤導，「明顯的事情」導致了一個微妙的錯誤）
• 輸入邊緣情況的描述需要特殊處理，因此解釋了爲什麼特殊處理代碼出現
• 提及要求或規範的要求，該要求或規範要求由特定的代碼行實施的行爲
• 對所採取的一系列步驟的頂級描述:(「首先得到輸入」，「現在剝離包裝器」 ，「finally parse it」），如果爲每個步驟調用的函數的名稱在上下文中是精心挑選和明確的，則不需要這些名稱，但我不打算爲泛型函數編寫一個無所事事的包裝器給它一個更具體的名稱爲一次性使用
• 文檔將被自動提取。這是批量評論的很大一部分，但我不確定它是否「真正重要」。
• 可能會成爲記錄界面的一部分，但並不是因爲它們將來可能需要更改，或者因爲它們是外部人員不需要的內部幫助器件。因此，對於實施者來說是有用的，而不是爲用戶所知。私人類不變量包含在這裏 - 每次你想依賴「這個成員是非空的」，或者「大小不超過容量」，或者「對這個成員的訪問權限，你真的想要通讀整個類嗎？必須同步「？最好在分配給成員之前檢查成員的描述，看看你是否被允許。如果有人沒有紀律以避免打破一個明確的評論不變，那麼，難怪他們所有的評論都是錯誤的...

其中一些東西是由綜合測試處理的，從某種意義上說，如果測試通過，然後代碼是正確的（哈），如果你也打開測試代碼，那麼你可以看到特殊的輸入案例，如果一些傻瓜隱藏了評論，做了我原來做的同樣的錯誤，並重構我的代碼做顯而易見的事情，那麼測試將失敗。這並不意味着在閱讀代碼的上下文中，評論不會處理它更好的。在這些情況中，沒有一個閱讀評論是代碼閱讀的替代品，它們旨在突出顯示重要但不明顯的內容。

當然，在自動文檔的情況下，它是完全合理的，可能更有用，可以單獨查看文檔。

在進行調試時，與進行更改相反，它的方式方式更有價值，可讓代碼自行解釋。評論不太有用，尤其是那些私有的不變式，因爲如果你正在調試，那麼編寫代碼+評論的人有一個錯誤的合理機會，所以評論可能是錯誤的。從好的一面來看，如果您看到的評論不能反映代碼的功能，那麼您很可能發現了一個錯誤。如果你只是看到代碼的作用，那麼你可能需要一段時間才意識到代碼的作用並不是它應該做的。

有時候，好的命名可以很快地取代評論。但是，如果名稱錯誤，名稱可能與註釋一樣具有誤導性。而且，說實話，名稱通常至少有點誤導或模棱兩可。我懷疑那篇博客的作者是否會用「var1，var2，func1，func2，class1，class2 ...」替換所有的名字，只是爲了確保他們沒有被原作者的分心代碼的意圖不正確。我認爲說「評論總是錯誤的」並不是說「變量名總是錯誤的」。它們是由同一個人在同一時間以相同的目的書寫的。

Answer 6

評論爲什麼你正在做的事情，而不是你在語法上做了什麼。