好的 Java 程序，注释的比例一般到多少？

Question

写了个模块，边写代码边写注释，完了之后发现注释比例接近50%了……
关键是，这50%大多是文件、类、属性、方法前面的 JavaDoc，代码流程里面的注释其实不多。
我删掉了很多废话，但实在是删不动了。
求问，注释比例这么大，是不是程序设计上出现了一些问题？比如模块划分得过细？

Answer 1

好程式碼本身就是註釋，至於作者版本資訊之類的內容，根本就不該放在原始碼裡，話說版本控制系統不就是乾這個的麼？
能一行註解不要又能讓別人看懂的程式碼才是好程式碼。

PS. API的註解相當於介面文檔，這對公用函式庫來說當然是必要的，要不然沒人知道你的函式庫怎麼用。

PPS. 註解的目的在於解釋程式碼中無法明示的問題，例如舊版的兼容性、採用特殊做法/演算法原因等，沒有目的的註解除了降低程式碼質量，唯一的用處就是滿足領導制定的KPI了。

Answer 2

昨天剛看了華為的java程式規格裡面有說到這個問題:30%

Answer 3

不覺得註解要有一定比例，當你看不懂時，文件就是救命稻草，顯然是越多越好！

JavaDoc本身就非常有用的。

Answer 4

我聽過一句話，好的程式碼它本身就是註解。
程式碼如果寫得可讀性好，其實註解就沒那麼重要。

Answer 5

註解比例大不大和你的模組設計的合不合理沒有直接關係。
舉個例子你看看android Activity的註解和你的比較一下
https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/Activity. java

Answer 6

能讓人比較快的看懂就可以。你可以讓另外一個人看，自己在旁邊。那個人看不懂哪了，你就在那兒加個註釋。這樣比較合適。

Answer 7

註解要解釋的不是這段東西是幹嘛的，而是為什麼要這麼做。

Answer 8

使用註解本身沒有嚴格標準，重在表達意義，提高可讀性。

Answer 9

註解多少也成為判定程序好壞的標準了? 我覺得多少得看你的程式會給什麼樣的人讀.

Answer 10

註解也應該遵循80-20原則：

• 重要的，複雜的，容易誤解的程式碼，不要吝惜註釋，註釋不要一行行重複程式碼，而是解釋你的意圖
• 不重要的，不複雜的，簡單明了看方法名字就知道做什麼的程式碼，不需要註解

引用Knuth，電腦程式應該是寫給人看的，只是剛好可以被電腦執行罷了。從這一點出發，程式碼應該是主要的內容，而註釋就是類似腳註、備註，大多數情況下不看也不影響原文，關鍵的地方解釋背景、釋疑等。

所以不必關心比例。