我正在为uni的最后一年CS undergrad项目编写Java应用程序。在过去几年中，我们被告知使用CheckStyle代码是必须的。但是，我发现使用默认的CheckStyle配置要求我为每件事编写一个JavaDoc。甚至明显的实例字段和方法，其中名称和实际代码足以描述该代码片段的作用，这要求我编写JavaDoc注释。
老实说，我发现这个重复，只是让我的代码混乱。如果没有所有这些评论，我发现我的代码更具可读性和更短性，这使我在需要查看课程等时能够更好地概述。
问题是，如果checkstyle强调它是一个问题（缺少JavaDoc）并且我们被告知使用CheckStyle没有例外，那么我怀疑我会丢失标记，这是我想要的最后一件事。我引用了这本优秀的书： 马丁，罗伯特C.（2008-08-01）。清洁代码：敏捷软件工艺手册（第54页）。培生教育（美国）。
正确使用评论是为了弥补我们在代码中表达自己的错误。请注意，我使用了失败这个词。我的意思是。评论总是失败。我们必须拥有它们，因为我们不能总是弄清楚如何在没有它们的情况下表达自己，但它们的使用并不值得庆祝。因此，当您发现自己处于需要编写注释的位置时，请仔细考虑并查看是否有某种方法可以转换表并在代码中表达自己。每当你用代码表达自己时，你应该拍拍自己。每当你写评论时，你都应该做鬼脸并感受到表达能力的失败。为什么我这么评论？因为他们撒谎。并非总是，而且不是故意的，而是经常的。评论越老，并且距离它描述的代码越远，它就越可能是完全错误的。原因很简单。程序员无法实际维护它们。
我不能说我是多么全心全意地赞同上述内容。这些评论只不过是我眼中的一团糟。如果相关，我也有意见。
所以，我的问题归结为以下几点：我是否应该坚持自己的信念和阅读上述书籍所获得的知识/建议，或者我是否应该遵守CheckStyle标准并消除因缺乏标准而遭受损失的风险JavaDoc评论？
答案 0 :(得分：3)
你说：
但是，我发现使用默认的CheckStyle配置要求我为每件事编写JavaDoc。即使是明显的实例字段和方法，其中名称和实际代码足以描述该代码片段的作用，也需要我编写JavaDoc注释。
还有：
我确实问过我的主管谁说最好坚持Sun的建议，即默认的checkstyle配置。
这两个陈述并不一致。
以下是实际的，传统的，古老的太阳编码会议文件（1999年修订）：
讨论非平凡或非显而易见的设计决策是合适的，但要避免重复存在于代码中（并从中清除）的信息。冗余评论很容易过时。通常，避免在代码发展过程中可能会过时的任何注释。
并不是说每个成员都需要发表评论。
我认为很明显，对于“明显的实例字段”或“名称和实际代码充分描述该代码所做的方法”的方法，不需要注释。无论是您的主管的指令还是您对它的解释都会在Sun编码约定和默认的Checkstyle配置之间产生等价。
值得注意的是，Sun编码约定是由编写Java本身的程序员编写的。这是一项非常特殊的工作;他们不仅需要生成有效的代码，并且维护人员可以理解这些代码，而且因为他们正在制作一个标准的库，它只能以二进制形式分发，这是可以理解的，而且在许多情况下完全是由签名和仅评论。我认为将20世纪90年代开发的规则应用于今天编写的应用程序代码实现Java本身是非常愚蠢的。这就像利未记一样过着你的生活。