评论约定答案

【问题标题】：Commenting Conventions评论约定
【发布时间】：2010-11-03 05:18:26
【问题描述】：

我想知道评论的一些准则是什么？我正在用Java编写类。我想要可读的代码。在另一个问题中，有人告诉我“如何”为困难的代码部分保留 cmets。有人告诉我，我的代码 cmets 添加了未知信息。评论不仅适用于读者。它们还提醒作者他们的初衷并帮助匹配分组符号。

我是 Java 和 Stackoverflow 的新手。为什么我越来越讨厌？我认为这个网站旨在让程序员互相帮助。我觉得自己像个目标，因为我有一个投了 -3 票的问题。我们是来帮助新程序员的，还是来以牺牲他人为代价自豪地挺起胸膛？

【问题讨论】：

阅读有关提问的常见问题解答可能会很好。它提出的一个有效点是，您应该搜索该站点以查看是否已经提出并回答了问题。如果您发布已经回答的问题，您可能会被否决。请参阅stackoverflow.com/questions/36432/commenting-code 了解您的问题。
欢迎。如果您有 3 个或更多的反对票，您可以将它们换成同行压力徽章 :) 但是尝试使用搜索 stackoverflow.com/search?q=commenting 它有一些非常周到的问题和答案，关于何时以及何时不发表评论。
要么是重复问题，要么是网站在几年后因没有什么新问题可问而陷入停顿……任你选择。如果注释代码的问题如此简单，以至于阅读一些关于它的问题的答案就可以终生解决问题，那么它就不会一直被问到了。这是一个难题，每个人的情况都不一样。例如，Java 新手可能需要评论三元运算符的使用，因为他们可能不记得它是什么。有经验的程序员会觉得这没什么用，但每个人的情况都不同。
Daniel Straight：理解这个站点应该是一个权威的信息存储库，而不是信息被分散十亿次。投票以重复结束。

标签： java comments

【解决方案1】：

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

可读的 cmets 更多的是个人喜好问题。有些人喜欢 cmets 遵循用于写书的语法规则，而另一些人则不太关心语法内容。

【讨论】：

【解决方案2】：

我评论的大事：

算法的名称。例如，如果我正在编写一个算法来计算两点之间的直线上的像素，我会留下评论说它是 Bresenham 算法的实现。
如果我要向函数发送硬编码的魔法值（例如 true、null、42 等），我会评论该值所代表的含义。
如果我实现一个数据结构，我喜欢评论说它旨在优化哪些操作。例如，如果我正在实现一个队列（诚然，您会为队列使用框架），我会说类似 FIFO 数据结构，具有 O(1) 的插入、删除和大小。
我尝试在名称未揭示实现的所有复杂性的每个类和方法的顶部留下注释。但是，我经常犹豫要不要这样做。通常情况下，当遇到这个问题时，重构是更合适的。

【讨论】：

代码本身确实无法捕捉到的一些优秀点。事实上，为算法命名一个方法是一个非常糟糕的主意，因为更改算法将需要更改 API 以保持一致。存在类似的解释来说明您的其他观点如何真正需要使用 cmets。荣誉。

【解决方案3】：

不同的人有不同的风格，所以在某种程度上，你在这里读到的任何东西都只是某人的建议。评论没有冷酷的硬性规定。

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

您将 Javadoc cmets 放在类、方法或实例变量的开头来描述它们的作用。有标准的方法来格式化评论中的数据，它们是标签。一些常见的标签是@author 和@version。您可以在此处查看 Sun 关于编写 Javadoc cmets 的一些建议：http://java.sun.com/j2se/javadoc/writingdoccomments/

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

我希望这可以帮助您大致了解如何在 java 中使用 cmets。我的建议部分来自于我在大学的 Java 入门课程中担任的助教工作，部分来自于在工业界工作。其他不同背景的人可能会有更多建议。

【讨论】：

【解决方案4】：

注释是为代码的读者准备的。当然，代码的读者也可能是作者。但无论哪种方式，你都想告诉读者他们不能从代码中轻易看到的东西。过多或冗余的 cmets 往往会与实际代码不同步。

【讨论】：

【解决方案5】：

如果您在两周后返回您的代码，并且无法轻松弄清楚自己做了什么，那么它要么需要更多的 cmets，要么进行重构以使代码更清晰。

也就是说，cmets 的指导方针应该来自您工作场所的政策，或者就您而言，应该来自您的老师。如果你的老师说你在某个地方不需要 cmets，那你就不需要。

完成课程后，请随意发表评论。

【讨论】：

【解决方案6】：

我会遵循以下帖子中提到的 Stack Overflow 准则：

【讨论】：