Question

有时很难确定你何时为某人写了足够的评论以了解你的意图。

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

您对此有何看法？

Answer 1

评论不能解释你在做什么。他们在那里解释你为什么要这样做。

Answer 2

这个论点是基于一个错误的困境：你的代码是一个可怕的憎恶，你写了大量的评论来解释每一个陈述和表达，或者你的代码是美丽的诗歌，你的祖母可以理解，没有任何文件

实际上，你应该为后者而努力（好吧，也许不是你的祖母而不是其他开发者），但要意识到有时候几条评论会消除歧义，或者让接下来的十行代码如此多更平淡。倡导根本没有评论的人是极端分子。

当然，应避免无偿评论。没有任何评论可以帮助更糟糕的代码更容易理解。他们可能只是让事情变得更糟。但除非你只编写琐碎的系统，否则有时候评论会澄清正在做出的设计决定。

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

正确地确定评论的实际存在时间是关键。

Answer 3

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

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

顺便说一下 - 你可以越接近伪代码，你的代码就会越自我解释。这是高级语言的特权;很难自我解释汇编代码。

Answer 4

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

我正在解决性能问题。开发人员认为他发现了瓶颈的根源;一段因某种原因要睡觉的代码。这段代码没有任何评论，没有关于为什么的背景信息。我们删除了块并重新测试。现在，应用程序在负载下失败，而不是之前。

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

Answer 5

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

例如：

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

在这种情况下，getContact不需要注释

Answer 6

瞄准不需要评论的代码，但如果你错过的话，不要打得太多。

Answer 7

我认为评论足够让你理解它，如果你不得不在以后的生活中审查你的代码就足够了。

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

我同意编写可读代码可能是最重要的部分，但不要遗漏评论。花些额外的时间。

Answer 8

可读代码应该是第一优先级。正如保罗·汤姆林（Paul Tomblin）已经写过的那样，评论集中在为什么是部分。

Answer 9

我尽量避免评论。代码应该是自我解释的。正确命名变量和方法。在具有良好名称的方法中打破大型代码块。编写做一件事的方法，你为它们命名的东西。

如果您需要撰写评论。做空。我经常感觉如果你需要详细说明为什么这个代码块会这样做，并且你已经遇到了设计问题。

Answer 10

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

这样的东西没用，绝对降低可读性：

/// <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)
{
}

Answer 11

基本上，在类/方法/函数声明的开头放置一个好的但可能简短的注释，并且 - 如果需要 - 在文件开头的介绍性注释，注释在不是这样的时候是有用的-common或not-so-clear-transparent操作被编码。

所以，例如，你应该避免评论显而易见的事情（i ++;在之前的例子中），但你知道的不那么明显和/或更棘手应该得到一些清晰，不引人注意，精彩，完整的评论，自然而然地获得了历史上最清晰的代码的诺贝尔奖;）。

并且不要低估评论应该也很有趣的事实;如果你能在智力上取笑它们，程序员会更加高兴地阅读。

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

就我个人而言，我并不是自我记录代码的忠实粉丝（也就是代码中没有单一的诅咒）：几个月之后你就写了它（我的个人规模只有几天），你很可能不会'告诉选择这种设计的真正原因，以表示你的智力，那么其他人怎么样呢？

评论不仅仅是代码行中的绿色内容;它们是你的大脑更愿意编译的代码的一部分。作为braincode的资格（笑）我无法肯定评论不是你正在编写的程序的一部分。它们只是它的一部分，而不是指向CPU。

Answer 12

通常情况下，我是文档评论的粉丝，清楚地说明了您编写的代码的意图。像NDoc和Sandcastle这样的漂亮工具提供了一种很好的，一致的方式来编写该文档。

但是，多年来我注意到了一些事情。

大多数文档评论并没有真正告诉我任何我无法从代码中收集到的内容。当然，这假设我可以从源代码开始做出正面或反面。
评论应该用于记录意图，而不是行为。不幸的是，在绝大多数情况下，这不是他们的使用方式。像NDoc和Sandcastle这样的工具只会通过提供过多的标签来传播不正确的评论用法，这些标签鼓励你提供评论，告诉读者他应该能够从代码本身中辨别出来的东西。
随着时间的推移，评论往往与代码不同步。无论我们是否使用文档软件，这都是正确的，文档软件旨在使文档更容易，因为它使文档更接近它描述的代码。即使文档就在方法，属性，事件，类或其他类型旁边，开发人员仍然很难记住在内在行为发生变化时更新它。因此，文档失去了它的价值。

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

如果使用正确，评论可以具有巨大的价值。但这意味着要知道它们最适合用于什么，并将它们的使用限制在该范围内。如果你没有做到这一点，你最终得到的是过多的评论，这些评论是错误的，误导性的，并且是繁忙工作的来源（成本增加），因为你现在必须要么删除它们，要么以某种方式纠正它们。

有必要制定一种策略，以有意义的方式使用评论，以防止他们成为时间，精力和金钱。

Answer 13

研究表明，当您对10行代码有大约1行注释时，会发生最佳可读性。当然，这并不是说你需要将你的口粮保持在1/10并且如果你过去就要惊慌失措。但这是一个很好的方式来让你知道你应该评论多少。

还记得评论是代码味道。也就是说，它们可能表示代码不好，但不一定如此。这样做的原因是更难理解的代码被更多地评论。

代码中的更多注释或只是简单，可读，可维护的代码就足够了？

13 个答案: