10

有时真的很难决定你什么时候写了足够多的评论让别人理解你的意图。

我认为人们需要更多地专注于编写可读、易于理解的代码，而不是包含大量注释来解释发生的每一个细节。

您对此有何看法？

4

13 回答 13

30

没有评论来解释你在做什么。他们在那里解释你为什么这样做。

于 2009-02-13T13:37:51.720 回答
12

这个论点是基于一个错误的困境：要么你的代码是一个可怕的可憎之物，你写了大量的注释来解释每一个语句和表达式，或者你的代码是美丽的诗歌，你的祖母可以理解，根本不需要文档。

实际上，您应该争取后者（好吧，也许不是您的祖母，而是其他开发人员），但要意识到有时几条注释会消除歧义或使接下来的十行代码更加简单。根本不主张评论的人是极端分子。

当然，应避免无端评论。再多的评论都不会帮助糟糕的代码更容易理解。他们可能只会让情况变得更糟。但是，除非您只是在编写琐碎的系统，否则有时评论会澄清正在做出的设计决策。

这在捕获错误时会很有帮助。有文化的代码看起来完全合法，但完全错误。没有评论，其他人（或六个月后的你）不得不猜测你的意图：你是故意这样做的，还是意外？这是错误，还是其他地方？也许我应该参考设计文档...评论是内联文档，在您需要的地方可见。

正确决定何时真正需要评论是关键。

于 2009-02-13T13:51:35.413 回答
5

尝试使代码自我解释。最重要的事情之一是为类、函数、变量等使用有意义的名称。

评论不能自我解释的部分。琐碎的注释（例如 i++; // 将 1 添加到 i）使代码更难阅读。

顺便说一句 - 您可以工作的伪代码越接近，您的代码就越容易自我解释。这是高级语言的特权；很难编写自解释的汇编代码。

于 2009-02-13T13:41:50.383 回答
2

并非所有代码都是自记录的。

我现在正在解决性能问题。开发者以为他发现了瓶颈的根源；由于某种原因要休眠的代码块。没有关于这段代码的评论，也没有关于它为什么存在的上下文。我们删除了块并重新测试。现在，该应用程序在以前没有的负载下失败了。

我的猜测是有人以前遇到过性能问题并放入此代码以缓解问题。这是否是正确的解决方案是一回事，但一些关于为什么有这段代码的评论现在将为我们节省一个痛苦的世界和大量的时间......

于 2009-02-13T13:56:29.490 回答
1

Aim for code that needs no comments, but don't beat yourself up too much if you miss.

于 2009-02-13T14:55:36.523 回答
1

为什么需要评论。方法的名称应该足够清楚，您不需要注释。

前任：

//  This method is used to retrieve information about contact
public getContact()
{
}

在这种情况下 getContact 不需要评论

于 2009-02-13T13:54:06.283 回答
0

基本上，在类/方法/函数声明的开头放置一个好的但可能是简短的注释，并且 - 如果有必要 - 在文件开头的介绍性注释，当一个不那么常见或不那么清楚透明的操作被编码。

因此，例如，您应该避免评论明显的内容（i++; 在前面的示例中），但是您所知道的不太明显和/或更棘手的内容应该得到一些清晰、不令人困惑、出色、完整的评论，这自然会出现历史上最清晰的代码获得诺贝尔奖；）。

并且不要低估评论也应该很有趣的事实；如果你能在智力上取笑他们，程序员会更乐意阅读。

因此，作为一般原则，评论往往不会被压倒，但是当你必须写一个时，请确保它是你能写下的最清晰的评论。

就我个人而言，我不是自我记录代码的忠实粉丝（又名代码 w/oa 一个该死的斜线星）：几个月后你已经写了它（这只是我个人规模的几天）很可能你无法告诉选择这样的设计来代表你的智慧的真正原因，那么其他人怎么可能呢？

注释不仅仅是代码行中的绿色东西；它们是您的大脑更愿意编译的代码部分。有资格成为大脑代码（笑）我不能肯定评论不是你正在编写的程序的一部分。它们只是不针对 CPU 的部分。

于 2009-02-13T16:08:36.567 回答
0

我认为足够的评论以便在以后必须审查代码时能够理解它就足够了。

我认为如果您为每个人发表评论会浪费很多时间；走这条路可能会让你的代码更难理解。

我同意编写可读代码可能是最重要的部分，但不要遗漏注释。多花点时间。

于 2009-02-13T13:39:20.483 回答
0

可读代码应该是第一优先级。正如 Paul Tomblin 已经写过的那样，评论的重点是为什么部分。

于 2009-02-13T13:40:39.777 回答
0

我尽量避免评论。代码应该是不言自明的。正确命名变量和方法。打破具有好名字的方法中的大代码块。编写做一件事的方法，也就是你为它们命名的那件事。

如果你需要写评论。让它简短。我经常有这样的感觉，如果你需要详细说明为什么这个代码块会这样做，那么你已经对设计有问题了。

于 2009-02-13T13:46:16.847 回答
0

仅在添加内容时发表评论。

像这样的东西是无用的，并且肯定会降低可读性：

/// <summary>Handles the "event" event</summary>
/// <param name="sender">Event sender</param>
/// <param name="e">Event arguments</param>
protected void Event_Handler (object sender, EventArgs e)
{
}
于 2009-02-13T14:01:43.503 回答
0

通常，我喜欢清楚地说明您正在编写的代码的意图的文档注释。NDoc 和 Sandcastle 等漂亮的工具提供了一种很好的、​​一致的方式来编写该文档。

然而，这些年来我注意到了一些事情。

  • 大多数文档注释并没有真正告诉我任何我无法从代码中真正收集到的东西。当然，这假设我可以从源代码中找出正面或反面。

  • 注释应该用于记录意图，而不是行为。不幸的是，在绝大多数情况下，这不是它们的使用方式。NDoc 和 Sandcastle 之类的工具只会通过提供过多的标签来传播注释的错误使用，这些标签鼓励您提供注释，告诉读者他应该能够从代码本身中辨别出的事情。

  • 随着时间的推移，注释往往会与代码不同步。无论我们是否使用文档软件，这往往都是正确的，它声称使文档更容易，因为它使文档更接近它所描述的代码。即使文档就在方法、属性、事件、类或其他类型旁边，开发人员仍然很难记住在内在行为发生变化时更新它。因此，文档失去了它的价值。

值得注意的是，这些问题基本上是由于评论的滥用造成的。如果仅将评论用作传达意图的一种方式，那么这些问题就会像渡渡鸟一样，因为任何给定类型或其成员的意图都不太可能随着时间而改变。（如果是这样，更好的计划是编写一个新成员并通过引用新成员来弃用旧成员。）

如果使用得当，评论会产生巨大的价值。但这意味着知道它们最适合用于什么，并将它们的使用限制在该范围内。如果你不这样做，你最终会得到大量不正确、误导性的评论，并且是忙碌工作的来源（成本增加），因为你现在必须删除它们或以某种方式纠正它们。

制定一种以有意义的方式使用评论的策略，以防止它们成为时间、精力和金钱的沉没，这是值得的。

于 2009-02-13T21:25:14.887 回答
0

研究表明，当您对 10 行代码有大约 1 行注释时，就会出现最佳可读性。当然，这并不是说你需要将你的口粮保持在 1/10，如果你超过了就会恐慌。但这是让您了解应该发表多少评论的好方法。

还要记住，注释是一种代码味道。也就是说，它们可能表示代码错误，但不一定如此。原因是越难理解的代码注释越多。

于 2009-02-13T21:53:54.303 回答