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