有哪些不同的代码注释做法？
阅读代码注释，似乎普遍支持注释不能解释代码本身可以解释的任何内容。我查过的所有来源（不是很多，但仍然有一些）都说注释应该在更高的抽象级别上解释代码。
然而，与我交往和工作的领域的专家们都支持，更多的评论总比不够好，即使评论解释了读者/编码器可以从代码中解读的内容，但这种情况也有不同的级别，有些人可能比其他人更快地破译代码，因此为了安全起见，最好对含义不太明显的代码进行注释；毕竟，
“作为一名编码员，当您不必阅读实际代码时，它会帮助您，并且可以理解函数的英文功能，而不是尝试破译代码。有时，它甚至可能有助于编写在编码之前在注释和伪代码中写出函数；这将有助于不断提醒该函数应该做什么。”
就评论而言，这两种思想流派截然不同。这就引出了一个问题：
关于代码注释有哪些不同的思想流派，以及最流行的（以避免询问最好的，因为这是主观的）来源我可以阅读有关代码注释实践的内容吗？
Reading up on code commenting, there seems to be a general support for comments that do not explain anything the code itself can explain. All the sources (not that many, but a few still) I have looked up say that the comments should be explaining the code on a higher level of abstraction.
However, experts in the field I socialise and work with are supporting that more comments are better than not enough, that even if the comments explain something that the reader/coder can decipher from the code, there are different levels of this, and some people may decipher the code faster than others, so to be safe it would be better to comment code whose meaning is not painfully obvious; after all,
"it will help you, as a coder, when you don't have to read the actual code, and can understand what a function does in English, rather than try and decipher code. Sometimes, it might even help writing the function out in comments and pseudocode before coding it; It will help as a constant reminder of what this function is supposed to do."
These two are quite different schools of thought as far as comments go. Which begs the question:
What are the different schools of thought about code commenting, and what are the most popular (so as to avoid asking about the best ones, as that is subjective) sources I can read up on about code commenting practices?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（1）
这是一篇相当尖锐的文章，名为评论的艺术，位于 ic#code 。它并不完美（匈牙利表示法很糟糕，不应该强加给开发人员），但它仍然相当有趣。
作者正确地指出，您可能需要使用注释来实现不同的目的，并将它们分为 3 类：
第三类显然是这里讨论的有趣的一类。在我看来，注释应该描述代码为什么这样做，而不是如何这样做。例如，如果您的代码对列表进行排序，您应该首先解释为什么必须对列表进行排序 - 列表的排序从代码中是（或应该）显而易见的。
最后，关于注释最重要的一点是它们不被编译，并且对程序的行为没有影响。这似乎是显而易见的。这样做的结果是，在软件的维护阶段，代码中的错误可能会被修复，但注释通常保持不变，并且可能会记录不再观察到的行为。由于错误的文档甚至不如不存在的文档有用，因此修复注释和实际代码中的错误非常重要。
This is a fairly sharp write-up called The Fine Art of Commenting over at ic#code. It's not perfect (Hungarian notation is horrible and should not be inflicted on developers), but it is still fairly interesting.
The author correctly notes that there are different things you may want to use comments for, and splits them into 3 classes:
The third category is obviously the interesting one being discussed here. In my opinion, comments should describe why the code does why it does, and not how. For example, if your codes sorts a list, you should explain why the list has to be sorted in the first place - that the list is being sorted is (or should be) obvious from the code.
Finally, the most important thing about comments is that they are not compiled and have no effect on the behavior of the program. This may seem obvious. The consequence of this is that during the maintenance phase of the software, bugs in the code may be fixed, but the comments often remain unchanged, and may document behavior that is no longer observed. As wrong documentation is even less useful than non-existent documentation, it is very important to fix bugs in the comments as well as in the actual code.