java - 什么才算足够的评论？

Question

关闭。这个问题是 opinion-based 。目前不接受答案。

---

想要改进这个问题吗？更新问题，以便 editing this post 可以用事实和引文来回答它。 .

已关闭 8 年前。

Improve this question

我的计算机科学类(class)要求我开始对我的代码进行描述性注释，以便老师和其他学生在阅读时可以更好地理解它。作为 50% 的懒惰和 50% 的精英主义者，我不想为了让人们能够理解我的代码而注释掉每一行。我不想注释掉每个方法，除非确实有必要(老师只要求他理解正在发生的事情，而不必尝试解释每一行代码)。在计算机科学领域，什么被认为是“足够的评论？”

Answer 1

普遍接受的评论准则是:

• 重要的类应该有 JavaDoc 来描述它们的用法/目的。记录对象的线程安全性通常也很有用。
• 基于方法名称的非平凡/非显而易见的方法应该有 JavaDoc。理想情况下，应记录对参数的任何要求(有关空值等的行为)，以及对传入对象的任何修改。好的经验法则是回答:
  • 此方法需要什么
  • 它产生/保证什么(以及何时抛出异常)
  • 它修改了什么(如果有的话)
• 任何复杂或不明显的代码行都应该被注释
  • 这个魔法常数从何而来
  • 为什么要这样做(如果不明显)
• 必要时可以对类变量进行注释。这不太标准，但有时注释变量以指示其用途很有用。

避免仅仅重复代码正在执行的操作的注释。例如

// Set x to 4 before the loop
x = 4;
for (int i = 0; i < x; i++)

但是，如果合适的话，请评论这样做的原因:

// Set x to 4 since we are guaranteed to only have 4 threads
x = 4;
for ...

至少，您应该有良好的方法注释(认为这是最重要的)，以及对您的类的粗略概述注释。我认为任何低于此的内容都是不专业的，并且是拒绝代码审查。