好的 Java 程序,注释的比例一般到多少?

fish748
  • 191

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

回复
阅读 11.4k
11 个回答

代码流程里面里面为何要那么多注释?
你把每一块代码用了什么算法干了什么写清楚就足够了
没必要每一句都写一个

注释也应该遵循80-20原则:

  • 重要的,复杂的,容易误解的代码,不要吝惜注释,注释不要一行行重复代码,而是解释你的意图
  • 不重要的,不复杂的,简单明了看方法名字就知道干什么的代码,不需要注释

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

所以不必关心比例。

注释多少也成为判定程序好坏的标准了? 我觉得多少得看你的程序会给什么样的人读.

使用注释本身没有严格标准,重在表达含义,提高可读性。

注释要解释的不是这段东西是干嘛的,而是为什么要这么做。

能让人比较快的看懂就可以。你可以让另外一个人看,自己在旁边。那个人看不懂哪儿了,你就在那儿加个注释。这样比较合适。

昨天刚看了华为的java编程规范里面面有说到这个问题:30%

我听过一句话,好的代码它本身就是注释。
代码如果写得可读性好,其实注释并不那么重要。

好代码本身就是注释,至于作者版本信息之类的内容,根本就不应该放在源代码里,话说版本控制系统不就是干这个的么?
能一行注释不要又能让别人看懂的代码才是好代码。

PS. API的注释相当于接口文档,这对于公共库来说当然是必需的,要不然没人知道你的库怎么用。

PPS. 注释的目的在于解释代码中无法明示的问题,比如旧版本的兼容性、采用特殊做法/算法原因等,没有目的的注释除了降低代码质量,唯一的用处就是满足领导制定的KPI了。

不觉得注释要有一定比例,当你看不懂时,文档就是救命稻草,显然是越多越好!

JavaDoc本身就非常有用的。

撰写回答
你尚未登录,登录后可以
  • 和开发者交流问题的细节
  • 关注并接收问题和回答的更新提醒
  • 参与内容的编辑和改进,让解决方法与时俱进
你知道吗?

宣传栏