Java 评论公约

我想知道评论的一些准则是什么？我正在用Java编写课程代码。我想要可读的代码。在另一个问题中，我被告知“如何”注释应该保留给代码的困难部分。我被告知我的代码注释没有添加任何已知信息。评论不仅仅是给读者的。它们还提醒作者它们的初衷，并帮助匹配分组符号

---

我不熟悉Java和Stackoverflow。为什么我变灰了？我以为这个网站是为了让程序员互相帮助而设计的。我觉得自己像个靶子，因为我有一个以-3票表决的问题。我们来这里是为了帮助新程序员，还是为了以牺牲他人为代价而自豪地鼓起胸膛？

我将遵循以下帖子中提到的堆栈溢出准则：

---

如果您在两周后回到代码中，无法轻松了解自己做了什么，那么要么需要更多的注释，要么需要重构以使代码更清晰

这就是说，评论的指导原则应该来自你的工作场所的政策，或者在你的情况下，来自你的老师。如果你的老师说你在某个地方不需要评论，那么你就不需要了

---

完成课程后，您可以随意以任何方式进行注释。

注释仅供代码读者使用。当然，代码的读者也可能是作者。但是无论哪种方式，你都想告诉读者一些他们从代码中看不到的东西。过多或多余的注释往往与实际代码不同步。

不同的人有不同的风格，因此在某种程度上，你在这里读到的只是某人的建议。评论没有冷酷无情的规则

关于Java中的注释，您应该知道的最重要的事情是Javadocing。它是一种特殊类型的注释，可以解析出来并在IDE（如Eclipse和Netbeans）中使用，以帮助简化编码过程。Javadoc注释以/**开头，以*/结尾。这与常规的多行注释类似，但在第一行中有两个星号

将Javadoc注释放在类、方法或实例变量的开头，以描述它们的功能。有一些标准方法可以格式化注释中的数据，这些方法是标记。一些常见的标记是@author和@version。您可以在这里看到Sun关于编写Javadoc注释的一些建议：

之后我喜欢做的是使用单行注释（双斜杠//）来描述我的逻辑。如果我需要不止一行，我将只使用多个单行注释。这种技术的优点是，如果以后需要注释大量文本，可以使用常规的多行注释/**/而不用担心嵌套注释问题

---

我希望这能帮助您大致了解如何在java中使用注释。我的建议一部分是因为我在一所大学的Java入门课程中担任助教，另一部分是因为我在工业界工作。其他不同背景的人可能会有更多的建议。

我评论的大事：

• 算法的名称。例如，如果我正在编写一个算法来计算两点之间直线上的像素，我会留下一条评论，说这是Bresenham算法的实现

• 如果我向一个函数发送一个硬编码的、神奇的值（例如true、null、42等），我会注释该值代表什么

• 如果我实现了一个数据结构，我喜欢评论它是为了优化什么操作而设计的。例如，如果我正在实现一个队列（诚然，你会使用一个队列框架），我会说类似FIFO数据结构的东西，带有O（1）插入、删除和大小

• 我试图在每个类和方法的顶部留下一条注释，这些类和方法的名称不能揭示实现的所有复杂性。然而，我经常犹豫是否要这样做。通常，当面临这个问题时，重构更合适

---

首先，拥有可读的代码和可读的注释是两件完全不同的事情。可读代码是使用好的变量、方法、类名等的代码

---

易读的评论更多的是个人品味的问题。有些人喜欢评论遵循语法规则，而有些人则不在乎语法方面的东西

阅读有关提问的常见问题解答可能会更好。它提出的一个有效的观点是，您应该搜索该网站，看看是否已经提出并回答了一个问题。如果你发布已经回答的问题，你可能会被否决。看看你的问题。欢迎。如果你有3张或3张以上的反对票，你可以用它们来换取“同侪压力”徽章：）但是试着使用搜索，它有一些非常深思熟虑的问题和答案，关于什么时候和什么时候不发表评论。问题可能会重复出现，或者网站在几年后因为没有什么新的问题而停滞不前。。。你挑吧。如果注释代码的问题如此简单，以至于阅读一些关于它的问题的答案可以解决一辈子的问题，那么它就不会一直被问到。这是一个困难的问题，每个人的处境都不同。例如，Java新手可能需要对三元运算符的使用进行注释，因为他们可能不记得它是什么。一个有经验的程序员会发现这没用，但每个人的情况都不同。丹尼尔·斯特朗：要知道，这个网站应该是一个权威的信息存储库，而不是让这些信息分裂十次。投票以重复的方式结束。代码本身无法捕捉到的一些优秀点。事实上，为算法命名一个方法是一个非常糟糕的主意，因为改变算法需要改变API才能保持一致。有类似的解释可以说明你是如何做到的