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

Question

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

Answer 1

Good code itself is a comment. As for content such as author version information, it should not be placed in the source code at all. Isn’t that what the version control system does?
Code that can be understood by others without a single line of comments is good code.

PS. API comments are equivalent to interface documentation, which is of course necessary for public libraries, otherwise no one will know how to use your library.

PPS. The purpose of comments is to explain problems that cannot be stated clearly in the code, such as compatibility of old versions, reasons for using special practices/algorithms, etc. Comments without purpose, in addition to reducing code quality, are only used to meet the KPIs set by the leadership. .

Answer 2

I just read Huawei’s Java programming specifications yesterday and this issue was mentioned: 30%

Answer 3

I don’t think comments should have a certain proportion. When you can’t understand, documentation is a life-saving straw. Obviously, the more the better!

JavaDoc itself is very useful.

Answer 4

I have heard a saying that good code itself is a comment.
If the code is well written and readable, comments are actually not that important.

Answer 5

The size of the comment ratio has no direct relationship with the reasonableness of your module design.
For example, take a look at the annotations of android Activity and compare it with yours
https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/app/Activity. java

Answer 6

As long as it can be understood quickly. You can let another person watch while you watch. If the person doesn't understand something, just add a comment there. This is more appropriate.

Answer 7

The purpose of the comment is not to explain what this thing does, but why it is done.

Answer 8

There are no strict standards for using comments. The emphasis is on expressing meaning and improving readability.

Answer 9

Has the number of comments become a criterion for judging the quality of a program? I think the number of comments depends on what kind of people your program will read.

Answer 10

Comments should also follow the 80-20 principle:

• Don’t skimp on comments for important, complex, and easily misunderstood code. Comments should not repeat the code line by line, but explain your intention
• Unimportant, uncomplicated, simple and clear code that you can know what to do just by looking at the method name, no comments required

Quoting Knuth, computer programs should be written for people to read, but they just happen to be executed by computers. From this point of view, the code should be the main content, and comments are similar to footnotes and remarks. In most cases, it will not affect the original text if you don't read it. Key places explain the background, clear up doubts, etc.

So don’t worry about proportions.