相关代码之前或之后的注释[关闭]

假设注释不适合（或不能加入）它所适用的行，应该在代码之前还是之后写注释？

好吧，将来的读者无论在哪里都能最好地理解该评论的范围。换句话说，无论大多数程序员/脚本编写者在何处发表此类评论。

那么，大多数程序员/脚本编写者在何处发表评论：在其代码之前或之后？

如果您的答案仅适用于特定语言，请指出。

而且，如果您可以引用支持您答案的公认规范或指南，那就更好了。

我可以在行内注释，也可以在代码之前应用注释。注释的含义是对代码的功能有一些基本的了解，而无需阅读代码本身。因此，将注释放在其描述的代码之前更加有意义。

微软表示，以一点点注释开始程序是一种好的编程习惯。（他们没有提到在过程后进行注释）。MSDN 链接是关于VisualBasic的，但是它适用于我认为的大多数编程语言。

我更喜欢将注释放在它们所引用的代码之上，这比告诉以前的代码来解释一些凌乱的代码修复了一些棘手的错误更有意义，那就是告诉一个正在阅读代码的人而不是试图参考先前的代码。所以不要碰它。

我认为代码通常是从上到下阅读的。如果没有别的，肌肉记忆会导致我将注释与其下一行代码相关联。

通常，注释应该在行的TOP后面，缩进与作品相同。例如，在函数主体上方的注释，以及在关键算法开始上方的一个内衬注释。

原因是，当有人开始阅读它时，很明显的问题是为什么要以这种方式完成某件事？直到那个人不知道要滚动到什么位置才能知道答案。如果它在顶部，那么就在那里。

那么，大多数程序员/脚本编写者在何处发表评论：在其代码之前或之后？

在使用多种语言进行编程的多年中，我不记得看到任何一种语言的任何代码，都在注释所在的代码之后的新行中添加了注释。至少在美国，事实上的标准是在代码之前或在代码之后的同一行进行注释。在相关代码之后写您的评论会引起药物测试，精神病评估和/或用钳子和吹火炬约会。

我能想到的唯一例外是注释，它标记了先前注释过的部分的结尾，如下所示：

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

杰夫·拉斯金（Jef Raskin）发表了一篇经过深思熟虑的评论文章，值得一读。他没有说是在代码之前还是之后添加注释，但他确实说过他从来没有将它们插入行内，我敢打赌，他也不会在代码之后添加注释。

尝试仅在真正必要的地方发表评论；该代码应尽可能进行自我记录。

话虽如此，放置的位置可能取决于：如果对注释使用单独的一行，请将其放在实际代码之前。如果您在同一行上，请放在后面。

// this workaround is required to make the compiler happy
int i = 0;

VS.

int i = 0; // make the compiler happy

但永远不要：

int i = 0;
// this workaround is required to make the compiler happy

我实际上并不喜欢评论。在软件工程课程中，向我介绍了自我记录代码的思想。该代码是唯一获得100％保证的正确正确文档-注释需要进行更新，精心构建并具有相关性，否则它们的陷阱可能比没有注释更糟糕。直到我开始在C ++商店工作，并获得严格的样式指南和有意义的命名约定后，我才真正实现了这一概念的内化。

有时需要注释。很多时候，仔细的变量命名，对空格和分组的有意义使用以及代码本身的有意义的逻辑组织消除了注释的必要。

这实际上是对您问题的假装和有效性的否定，而不是对您所提出问题的答案。我仍然认为这很重要，可能会对您有所帮助，但我不是一个混蛋。如果没有，-1将主导我。

让注释出现在代码之前有助于读者了解他们将要遇到的代码的上下文。比将代码扔给他们并在混淆之后进行解释要更为人道。

好的，我将采用“之后”的情况：代码应该始终是主要文档，而注释（没有语义）就像括号中的解释。因此，将注释放在需要说明的代码下面，将代码作为主要说明，而仅使用注释进行澄清。例如，

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

如果将注释放在测试之前，那么读者将倾向于将注释作为主要内容阅读，并且可能不会仔细阅读代码，而不会意识到它们被误导了：

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

为了从技术写作中借鉴一些想法（至少使用英语），通常将注释和注意警告之类的内容放在说明或注意警告所适用的说明或部分之前。

我不明白为什么不能将代码视为技术写作的一种形式-每个块都是一条指令。像英语一样，大多数编程语言都是从左到右，从上到下阅读的。注释是有关代码的注释-它们可能会标识要修复的错误，或者将来的开发人员可能需要注意的事项。

遵循这种关系，将注释放在其引用的代码块上方似乎更合适。

注释可能需要放在一段代码的上方或下方，这取决于注释的种类：如果对代码的作用给出了简短的说明，则它必须在代码之前；如果它详细阐明了有关代码工作方式的技术细节，则需要遵循该代码。

幸运的是，注释可以在一段代码的上方或下方移动，并且通过适当使用空白行，仍然可以确定注释与哪段代码有关。当然，不注意空行使用的程序员不会知道我在说什么。如果您是其中之一，请跳过此答案，继续您的生活。但是关注空白行的程序员非常清楚，空白行用于将代码分成逻辑实体。因此，如果您看到以下内容：

[blank line]
/* comment */
{ code }
[blank line]

您知道注释属于代码，并且它告诉您代码的作用。而如果您看到以下内容：

[blank line]
{ code }
/* comment */
[blank line]

再一次，您非常清楚注释属于该代码，并且可以澄清该代码如何执行其工作。

上面的评论是最好的。

如果您必须包含注释并且您的代码不是不言自明的，那么我宁愿不要被一段代码弄糊涂，然后看“啊，那是应该做的”。

代码可以（并且应该）是“自我记录”，但是如果您必须阅读并理解每一行代码以了解方法的工作原理，则可以。 If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

当我浏览了这个主题时，我发现大多数计算机可读文档系统（Doc XML，Doxygen，Java doc等）都希望注释出现在与之相关的代码之前-最好与该标准兼容。

我也同意SO线程- 我们应该在代码块之后而不是之前添加注释吗？..

我也很想知道...

我经常将注释（我的以及其他人的注释）转换为跟踪级别的日志语句。通常，这使您更容易理解将其放置在何处。

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

另一个优点是，当工作变得困难时，我可以打开日志跟踪并获取更详细的执行日志。