C# 突然出现一种难以忍受的写评论的欲望，是一个糟糕设计的症状吗？

想象一下。。。您已经编写了一些代码；实现了一些接口，使用了一些设计模式，通过了许多单元测试，提取了许多重构方法等等。你发展，发展，发展。。。但在某个神秘的时刻，出于某种原因，你内心的某些东西开始悄悄地告诉你，你现在应该写一篇评论。有些东西会让你觉得，如果你不写评论，就会遗漏一些东西，或者有些东西可能不太清楚

然后注释代码！：(

这可能是一个坏设计的秘密迹象吗

---

如果您发现自己处于这样一种情况，即如果您不在精神层面上对代码进行注释（！）瞬间，它不会完成它的任务<强>，我们能认为它是你的代码中一个可能的坏设计<强>的可靠的“强”症状吗？

有时候写注释比清理代码更容易，使它足够清楚地理解它做了什么和为什么。我通常在后面做，但是注释可以是最好的方法。s、 特别是，如果你生成javadocs。

我倾向于这样做，当我已经尝试了其他几种不起作用的方法时，我会努力阻止自己在几个月后回来，并再次尝试重构这些方法。

就我个人而言，我总是注释我的代码。没有长的行，但像这样的短的行

// parser starts here
...
// mail!

等等

然而，如果你有一个5行的脚本，注释可能有点过火了…尤其是如果你的文件名上写了

---

如果是为了你，你一个人，如果你愿意的话，你完全应该这样做。如果你和一个团队一起工作，我会一直这样做。只是为了通知其他人他们在看什么。

虽然我同意代码应该尽可能地自我文档化，但这并不总是足够的。如果你不写co，你能做的只有这么多一个很好的例子是，正如我的一位导师所说：“代码只能记录你做了什么，而不能记录你没有做什么。”

即使你有尽可能好的设计，也总会有地方需要你的评论来表达你的意图

注释可用于记录棘手的技术问题。如果问题很复杂，其实现将很复杂，需要记录

---

注释也可用于记录业务规则。这些规则将被表达为代码，但代码很少解释规则背后的原因。注释会使事情更清楚…

如果您觉得由于缺少某些内容而应该添加注释（可能是客户文档！），则这可能并不表示您的代码本身不好。如果您是因为某些内容不清楚而添加注释，则需要确定不清楚是因为代码很难，还是因为基础域很难。如果是代码，则需要重写它以使其更清楚。如果是域使其变得困难，请随意修改对于不熟悉相关领域的人，请对其进行广泛的注释，不要使用代码。

注释和糟糕的设计是两件不同的事情。注释有助于在更大的背景下理解某些事情。注释（以及一般的文档）有助于项目中的新手自己阅读

事实上，我们有一些不成文的规则，我们必须评论我们的东西。如果我想知道是否有人第一眼就能理解这一点，这已经是一个必要评论的标志

---

然而，这并不是一个糟糕设计的标志。

我把它作为一个asnwer，因为我认为它很重要。基本上我同意斯图尔特的观点：

---

前一份工作中的一种编码标准，据说只有在处理复杂的压缩或加密算法等计算异常困难的事情时才对代码进行注释。那家公司有我见过的最好的该死的代码，我在各种不同类型的公司工作过。

我非常同意对于支持自文档化代码的人，有一个地方我觉得他们忽略了注释的重要性：接口，以及在较小程度上的抽象方法比方法名称中描述的更复杂。唯一可以记录的方法是使用注释。

同上，请向Guillaume转达。我强烈不同意那些认为如果您只是将代码写得足够清楚，注释是不必要的人的说法

是的，如果只使用有意义的变量和函数名，某些类型的注释确实是不必要的。比如，为什么要写：

x17=bbq*rg; // Multiply price by tax rate to get tax amount

最好写：

taxAmount=price*taxRate;

当有人写了一条评论，只是重申任何有能力的程序员通过阅读代码应该能够立即说出的内容时，我觉得这令人难以置信地恼火。我不知道有多少次我看到过这样的无用评论：

x=x+1; // Add one to x

比如，哇，谢谢你告诉我“+”的作用。如果没有评论，我可能不得不用谷歌搜索它

但我发现至少有三种类型的评论非常有用：

解释某些大块代码背后的总体目的或方法的注释。这些注释为我提供了您为什么要这样做的线索。例如，“//当交货地点发生变化时，使用适用于新地点的税率重新计算销售税”.当然，我可以破解代码并最终弄明白你在做什么，但如果你事先告诉我，我就不必弄明白。这不是一个我们可以看到解决问题需要多长时间的游戏。只要告诉我答案就行了

注释解释了如何调用函数或如何使用API。例如，“要检索定价数据，首先调用contactPricingServer建立连接，然后为每个需要定价的项目调用getPrice，最后调用closeConnection释放资源。”如果我研究了所有可用的

// Set the sales status to "S" and the delivery date to today.
setSalesStatus("S");
setDeliveryDate(today);