什麼是不同的代碼評論做法？

Question

閱讀代碼評論，似乎普遍支持的評論，不解釋代碼本身可以解釋的任何東西。我查過的所有資源（沒有那麼多，但仍有一些）說，這些評論應該在更高級別的抽象層次上解釋代碼。

但是，我在社交和合作領域的專家都支持說，更多的評論總比不夠好，即使評論解釋了讀者/編碼人員可以從代碼中解讀的東西，但是這個層次有不同的層次，有些人可能會比其他人更快地解密代碼，所以爲了安全起見，最好是評論其意義不明顯的代碼; 「

」當你不必閱讀實際的代碼，並且可以理解函數在英文中做什麼，而不是嘗試和解密代碼時，它將幫助你作爲一個編碼器，有時候，它甚至可能有助於在編寫代碼之前在註釋和僞代碼中編寫函數;它將有助於不斷提醒此功能假設要做什麼。「

就評論而言，這兩者是完全不同的思想流派。這引出了一個問題：

什麼是關於代碼註釋思想不同的學校，什麼是最流行的（從而避免詢問有關最好的，因爲這是主觀的）來源，我可以讀了關於代碼評論的做法？

Answer 1

這是一個非常清晰的文字，名爲The Fine Art of Commenting而非ic＃代碼。這並不完美（匈牙利符號很可怕，不應該在開發者身上造成），但它仍然相當有趣。

作者正確地指出，有可能要使用徵求意見不同的東西，並把它們分成3類：

• 紀錄片的意見，例如版權信息，作者和版本和變化的信息。
• 功能註釋，這是您的各種「TODO」和「BUG」註釋，指出可能需要進一步關注的代碼區域。
• 解釋性意見，它解釋了代碼的作用。

第三類顯然是這裏討論的有趣之一。在我看來，評論應該描述代碼爲什麼會這樣做，而不是如何。例如，如果您的代碼對列表進行排序，您應該解釋爲什麼列表必須首先排序 - 列表正在排序（或應該）從代碼中顯而易見。

最後，關於註釋最重要的是它們沒有被編譯，並且對程序的行爲沒有影響。這看起來很明顯。這樣做的結果是，在軟件的維護階段，代碼中的錯誤可能是固定的，但註釋通常保持不變，並且可以記錄不再被觀察到的行爲。由於錯誤文檔比不存在的文檔更沒有用處，修復註釋中的錯誤以及實際代碼非常重要。