代碼評論寶石

Question

幾個月前，我確信有一個寶石，確保你已經評論了每一行代碼。或者至少每一個動作。如果你沒有，那麼在你執行某種耙子任務後，它會引起你的注意。

我不記得它被稱爲什麼。

但是，評論每一行代碼是否是一個好主意？我說的是，它鞏固了你的知識，爲你提供了最後一個改變來發現錯誤/安全漏洞，並且使未來的開發變得容易。

但是，在github中的項目和真正的稀疏評論。就我個人而言，我需要評論大多數行，然後纔開始意識到一段代碼的作用。這對大多數人來說不是這種情況嗎？做評論只是把代碼忍者絆倒了？

Answer 1

不，這不是一個好主意來評論每一行代碼。很多代碼是不言自明的。事實上，你應該努力使自己的代碼不言自明。

例如，你絕不會要評論如下：

sum = 1 + 3 

您應該保存您的意見對事情需要解釋。

我認爲你的意思是執行正確文檔的寶石。文檔是解釋方法或類的用途以及詳細參數和返回值的註釋。

關於您正在考慮的寶石，它可能是rubocop。

Answer 2

註釋的每一行代碼是一個可怕的想法：

1. 這是嘈雜和混淆源
2. 它成爲過時的平凡容易

事情發表評論：

1. Tricky和/或hacky代碼
2. 點複雜的算法
3. 爲什麼東西是做什麼它做

這些評論應該總是住在方法級別。

1. 如果一個代碼塊需要一個評論它也許應該是一個方法
2. 如果一行代碼需要評論它可能應該重構

代碼應該自己說話儘可能。適當的命名方式可以消除大量評論的需要。有些文檔可能絕對有必要，但對於大型結構性評論來說，將其排除在代碼之外以及在wiki中可能更有意義。