3

我正在为大学最后一年的 CS 本科项目编写 Java 应用程序。在过去的几年里，我们被告知在我们的代码中使用 CheckStyle 是必须的。但是，我发现使用默认的 CheckStyle 配置需要我为每一件事编写一个 JavaDoc。即使是名称和实际代码足以描述这段代码的作用的明显实例字段和方法，也需要我编写 JavaDoc 注释。

老实说，我发现这是重复的，只是弄乱了我的代码。如果没有所有这些注释，我会发现我的代码更具可读性和更短，当我需要查看类等时，这给了我更好的概览。

问题是，如果 checkstyle 将其突出显示为一个问题（缺少 JavaDoc），并且我们被告知要毫无例外地使用 CheckStyle，那么我怀疑我会失去分数，这是我最不想做的事情。我引用了这本优秀的书：Martin, Robert C. (2008-08-01)。清洁代码：敏捷软件工艺手册（第 54 页）。培生教育（美国）。

正确使用注释是为了弥补我们在代码中表达自己的失败。请注意，我使用了失败这个词。我是认真的。评论总是失败的。我们必须拥有它们，因为没有它们我们无法始终弄清楚如何表达自己，但使用它们并不是值得庆祝的理由。因此，当您发现自己处于需要写评论的位置时，请仔细考虑一下，看看是否没有办法扭转局面并用代码表达自己。每次在代码中表达自己时，都应该拍拍自己的后背。每次写评论，你都应该做鬼脸，感受一下自己表达能力的失败。为什么我对评论如此失望？因为他们撒谎。并非总是如此，也不是故意的，而是太频繁了。注释越旧，离它描述的代码越远，它越有可能是完全错误的。原因很简单。程序员实际上无法维护它们。

我不能说我是多么全心全意地同意上述观点。评论在我眼里不过是一团糟。在相关的地方，我确实有意见。

因此，我的问题归结为以下几点：我应该坚持自己的信念和通过阅读上述书籍获得的知识/建议，还是应该遵守 CheckStyle 标准并消除因缺乏 JavaDoc 注释而被标记的风险?

4

1 回答 1

3

你说：

但是，我发现使用默认的 CheckStyle 配置需要我为每一件事编写一个 JavaDoc。即使是名称和实际代码足以描述这段代码的作用的明显实例字段和方法，也需要我编写 JavaDoc 注释。

并且：

我确实问过我的主管，他说最好坚持 Sun 的建议，即默认的 checkstyle 配置。

这两种说法并不一致。

这是实际的、传统的、古老的 Sun 编码约定文件（1999 年修订）：

评论部分确实说：

讨论不平凡或不明显的设计决策是合适的，但要避免重复出现在代码中（并从代码中清除）的信息。多余的评论太容易过时了。一般来说，避免任何可能随着代码发展而过时的注释。

它并不是说每个成员都需要评论。

我认为这很清楚地表明，“明显的实例字段”或“名称和实际代码足以描述那段代码的作用的方法”不需要注释。您的主管的指令或您对它的解释在将 Sun 编码约定与默认 Checkstyle 配置等同起来时都会出错。

还值得牢记的是，Sun 编码约定是由编写 Java 本身的程序员编写的，并且是为编写 Java 本身的程序员编写的。那是一种非常特殊的工作；他们不仅需要生成有效的代码，并且维护者可以理解，还因为他们正在制作一个标准库，该标准库只能以二进制形式分发，这是可以理解的，并且在许多情况下完全指定，通过签名和单独评论。我认为将 1990 年代为实现 Java 本身开发的规则应用于今天编写的应用程序代码是非常愚蠢的。这就像按照利未记的方式过你的生活。

于 2012-11-17T23:42:02.023 回答