有哪些评论示例可以告诉您为什么而不是如何或什么？答案

【问题标题】：What are examples of comments that tell you WHY instead of HOW or WHAT?有哪些评论示例可以告诉您为什么而不是如何或什么？
【发布时间】：2013-07-21 16:19:58
【问题描述】：

首先，在这个问题上，我想远离关于源代码注释是好是坏的争论。我只是想更清楚地理解人们在谈论告诉你 WHY、WHAT 或 HOW 的 cmets 时的意思。

我们经常看到诸如“评论应该告诉你为什么；代码本身应该告诉你如何”之类的准则。在抽象层面上很容易同意该陈述。然而，人们通常会像教条一样放弃这一点，并离开房间而不做进一步的解释。我已经看到它在很多不同的地方和环境中使用，看起来人们可以就标语达成一致，但他们似乎在谈论完全不同的事情。

那么，回到这个问题：如果 cmets 应该告诉你 WHY，我们在说什么 WHY？这就是为什么那段代码首先存在的原因吗？这是那段代码应该做的吗？如果有人能给出清晰的解释，然后添加一些好的例子，我将不胜感激（实际上并不需要坏的例子，但可以随意添加它们以进行对比）。

请不要以重复或有争议的方式立即结束此问题。我努力使它非常客观。关于 cmets 是好是坏有很多问题，但没有一个具体的问题是什么是 cmets 的好例子来告诉你为什么。

谢谢，

【问题讨论】：

我认为这不是一个适合 SO 的问题。更有可能是程序员。SE。也许这已经有所帮助：programmers.stackexchange.com/questions/119600/….
谢谢菲利克斯，这肯定有帮助。另一方面，这个帖子有很多例子表明人们放弃了同样的诫命，然后没有提供清晰的解释或好的例子。

【解决方案1】：

评论有两个主要目的：

总结一下。很多人会说“当我们可以阅读代码时，为什么要记录这个方法？”，但是描述方法的用途/作用的一行文本通常比 30 行更容易阅读和理解代码，尤其是如果该代码调用了您可能还需要阅读的其他方法...
解释从代码中不明显的事情 - 为什么，或更详细地说明如何。简单的例子包括“我们必须添加新的 XmlElement 然后删除旧的，因为 .net 中的 ReplaceChild 方法不起作用！”，或“使用迭代 Newton-Raphson 方法求解 X”，或“我们不能在此处关闭端口，因为读取线程可能仍在运行”，或“在性能至关重要的情况下使用此方法，但请注意此方法可能会提供高达 5% 的错误结果”

【讨论】：