我想知道评论的指导原则是什么？我正在用Java编写课程。我希望有可读的代码。在另一个问题中，我被告知“如何”应该为困难的代码段保留注释。有人告诉我，我的代码评论没有添加任何已知信息。评论不仅适用于读者。它们还提醒作者他们的原意并帮助匹配分组符号。
我是Java和Stackoverflow的新手。为什么我变得贪婪？我认为这个网站旨在让程序员互相帮助。我觉得自己是一个目标，因为我有一个-3投票的问题。我们在这里是为了帮助新的程序员还是在这里为自己的胸膛而骄傲地为他人付出代价？
答案 0 :(得分：8)
不同的人有不同的风格，所以在某种程度上你在这里读到的只是某人的建议。评论没有冷酷的规则。
在Java中评论最重要的是Javadocing。这是一种特殊类型的注释，可以在IDE（如Eclipse和Netbeans）中进行解析和使用，以帮助简化编码过程。 Javadoc注释以/ **开头，以* /结尾，就像常规的多行注释一样，但在第一个注释中有两个星号。
您将Javadoc注释放在类，方法或实例变量的开头，以描述它们的作用。有一些标准方法可以在注释中格式化数据，这些是标记。一些常见的标签是@author和@version。您可以在此处查看Sun关于编写Javadoc注释的一些建议：http://java.sun.com/j2se/javadoc/writingdoccomments/
之后我喜欢做的是使用单行注释（双斜杠//）来描述我的逻辑。如果我需要多行，我将只使用多个单行注释。这种技术的优点是，如果您需要稍后注释掉大量文本，您可以使用常规的多行注释/ * * /而不必担心嵌套注释问题。
我希望这可以帮助您大致了解如何在java中使用注释。我的建议部分是我在大学的Intro Java课程中获得的助教工作的一部分，部分来自于在工业界工作。其他具有不同背景的人可能会有更多的建议。
答案 1 :(得分：6)
我将遵循以下帖子中提到的Stack Overflow准则：
答案 2 :(得分：4)
我评论的重要事项：
算法的名称。例如，如果我正在编写一个算法来计算两点之间的一行中的像素，我会留下一条评论，说它是Bresenham算法的实现。
如果我向函数发送硬编码的魔术值（例如，true，null，42等），我会评论该值代表什么。
如果我实现了数据结构，我想评论一下它的优化操作。例如，如果我正在实现一个队列（诚然，你会使用一个框架作为队列）我会说像FIFO数据结构这样的东西有O（1）插入，删除和大小。
我尝试在每个类和方法的顶部留下注释，其名称未显示实现的所有复杂性。但是，我常常犹豫不决。通常情况下，当遇到这个问题时，重构更合适。
答案 3 :(得分：1)
如果你在两周内回到你的代码而你不能轻易弄清楚你做了什么，它要么需要更多的评论，要么重构以使代码更清晰。
也就是说，评论指南应来自您的工作场所政策，或者您的情况，来自您的老师。如果您的老师说您不需要在某个地方发表评论，那么您就不会。
完成课程后，请随意以任何方式发表评论。
答案 4 :(得分：1)
评论是针对代码的读者。当然，代码的读者也可能是作者。但不管怎样，你想告诉读者他们从代码中看不到的东西。过多或冗余的注释往往与实际代码不同步。
答案 5 :(得分：1)
首先，具有可读代码和可读评论是两件完全不同的事情。可读代码是使用良好变量，方法，类名等的代码。
可读评论更多的是个人品味。有些人喜欢评论遵循用于写书的语法规则，而其他人则不会关心语法的东西。