好的 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，计算机程序应该是写给人看的，只是恰好可以被计算机执行罢了。从这一点出发，代码应该是主要的内容，而注释就是类似于脚注、备注，大多数情况下不看也不影响原文，关键的地方解释背景、释疑等。

所以不必关心比例。