评论做法？

Question

作为一名计算机工程专业的学生，​​我一直被迫为我所做的一切打上非常详细的评论。我可以看到这对团队项目或工作场所非常有用，但是当你在自己的项目上工作时，你会花多少时间评论？

作为一个我正在努力的个人项目变得越来越复杂我有时觉得我应该更多地评论，但我也觉得好像浪费时间，因为我可能是唯一一个正在努力的人。值得花时间和杂乱的代码吗？

思考？

编辑：这给了我很多思考。感谢您的输入！我没想到会有这么大的回应。

Answer 1

当代码不能时，考虑周全的评论会亮起。经过深思熟虑的功能和变量名称消除了对大量注释的需求。如果您发现有必要对所有内容进行评论，请考虑简化代码。

Answer 2

如果你看过6个月前写的代码，你会想知道为什么你没有更好的评论。

Answer 3

如果代码写得很好，使用简短的方法（参见Composed Method模式）和meaningful names，那么代码只需要很少的注释。只有解释“为什么”的注释才有用 - 解释“什么”的注释应该通过改进代码来代替它显而易见的。不应使用注释as an excuse来编写错误的代码。

公共API，特别是在封闭源应用程序中，可能是推荐使用全面javadoc的唯一地方 - 然后您需要付出努力来维护它们并使它们始终保持准确和最新。误导或过时的评论比没有评论更糟糕。最好通过编写代码并使用good names for the tests来记录代码的作用。

这本书Clean Code有一篇关于评论的好章节。

Answer 4

评论 - 或者更好的是，重新编码 - 现在任何不明显的事情。之后它将完全非显而易见。您可能会想，“但它会成为我”，但如果您的思维方式（以及编码方式）随着您的成长而发生变化现在对您来说显而易见对您来说可能并不明显后

Answer 5

单元测试等是代码文档的最佳形式。一些测试框架写出了一个关于被测试类应该做什么的规范，让人们很好地介绍了一段代码如何在纯英语中工作，同时也提供了非常干净的方式来实现测试本身。

示例是Scala的ScalaTest或RSpec for Ruby。

我发现除非有问题的代码需要一些奇怪的hacky东西，否则评论它通常是没有好处的。此外，它增加了很多开销，因为你必须维护注释......并且维护代码和测试已经足够了。

请记住，带有过时评论的代码比没有评论更糟糕！

很多时候，评论只是说代码所做的事情，这是浪费人力。如果没有，你的代码可能很糟糕，你应该重构它。

只需使用测试框架。

Answer 6

你读过Code Complete了吗？建议作为一个非常好的阅读，并找出CS教授钻喉咙的一些好方法。

代码评论分为两类：

1. 评论解释逻辑，制作 确保代码匹配 意图。人们常常写得很高 级伪代码并将使用它 在评论表中填写 模块的实际代码 做。然后他们留下评论为 可以使用的read-along 在以后的审查中。
2. 评论 解释模块的用法。认为 的javadoc。你的意图是为了 消费者了解你的原因 代码很重要。一个用途 javadocs在Visual Studio中 智能感知（因为我不使用 Eclipse idk）。它显示了评论 来自intellisense中的javadoc 徘徊。后来变得非常方便。

当教授要求您记录代码中的所有内容时，我发现将psuedocode的用法转换为实际代码就足够了。然而，在实践中我没有发现许多开发人员需要它，因为通常代码足以解释自己（当简单，写得很好，不依赖于技巧，以及使用描述性变量名称时）。

但如果我认为这一点不清楚，我仍会对意图发表意见。这只是一个最佳实践。

但我绝对会说读这本书。 ;）

Answer 7

如果你决定开源你的个人项目，人们会感谢你的评论（除非他们很糟糕）。如果你找到了一个非常棒的想法并且你的个人项目变成了一个企业，那么你将会招聘更多的开发人员，而你的评论将会很有价值。如果你的头部轻微受伤，那么当你重返工作岗位时，你会感激你的意见。

Answer 8

有些人将评论视为代码气味，表示代码可以使用更具描述性的名称和更好的结构。他们将修复代码，因此不需要注释。

这适用于很多情况。然而，一种有用的评论是'为什么'正在做的事情。有时修复是出于不明原因而在以后查看代码时不明显。注释不应该表达代码的作用（应该通过命名来涵盖）或它是如何做到的（再次，代码告诉你），所以保存你的评论为'why'。

我发现没有什么比单元测试更好的文档了。

Answer 9

每当我做一些不是自我记录的事情时，我都会发表评论。我会忘记我在做什么，除非我这样做。但我更喜欢编写代码，这些代码非常明显，以至于评论无济于事。在可能的情况下，代码应该足够清晰，以至于不需要数千行注释。

无论你做什么，都不要写这样的评论......

// add 1 to i
++i;

那是噪音。你实际上对这样的评论比没有评论更糟糕。

Answer 10

老实说，如果代码是明确的，则没有必要，但是当给定某些数据（可能不明显）时特定逻辑中断时，注释最佳。留下可能发生的问题的评论是一种很好的方法，可以帮助防止由于对期望（或特别是没有）数据的误解而导致的意外错误。

Answer 11

一个强硬的立场是：“如果你必须为你的代码写一个评论，你的代码就会被破坏”。而不是编写解释性注释，重构您的代码，以便评论变得不那么必要。这尤其适用于函数名称（包括它们的参数），因为它们往往被修改得最多，并且注释很少更新以匹配。

而不是：

// Compute average for the two times
int a = t1 + (t2 - t1) / 2;

写

int averageTime = AverageOfTimes(t1, t2);

int AverageOfTimes(int t1, int t2) {
    return t1 + (t2-t1); 
}

当我正在阅读其他人的代码时，陈旧的评论是WTF的主要原因之一。 过度评论被一些作者称为“代码气味”，包括“清洁代码”的作者。

就个人而言，我为每个类写了一个解释性注释（我主要用C＃和C ++编写代码），偶尔当我使用我想要引用的算法时。

Answer 12

评论对于单个项目以及组项目非常有用，尤其是当您需要在较长时间内维护或增强代码时。这种情况可能不适用于学校项目，但在工作场所它绝对适用。如果您曾经看过过去6个月写的代码，那么它可能也是由其他人编写的。

Answer 13

我发现 - 正如每个人都会告诉你的那样 - 如果你在几个月后回到代码中，你会忘记一切。也就是说，除了// ew.. hacked because X-beyond-my-control doesn't do Y correctly之类的评论之外，我几乎不会评论自己的代码。但这是因为代码本身写得非常干净，而且非常容易阅读。例如，所有变量和函数名称都是完全描述性的。我不使用缩写，除了相当长的单词，这些单词很明显，例如'info'。所有功能都非常简短。如果可能，所有功能都做一件事。如果可能，避免嵌套。逻辑相关的功能通过类或模块分组。

当我阅读其他人的代码时，我不会阅读评论。我读了代码。清晰和精心编写的代码和意大利面之间的区别远比任何评论重要。通常我不在乎他们的意图是什么;我想改变代码。要做到这一点很容易，它需要组织良好。所以评论是外围的。但也许这只是我。

Answer 14

从技术上讲，代码完全是自我记录。我喜欢评论任何不明显或特别复杂的东西。我倾向于在课堂上至少有一个总结，也许每个成员都有一个简短的模糊。当你必须在一个非常庞大而复杂的方法上编写大量的文档时，这通常是一个好的迹象，需要为重构器查看它。

foreach(var a in b.Items) //Enumerate the items in "b"
{
    if(a.FirstName == "Jones") //See if first name is Jones
.... 

你想要的东西在上面的中间，没有任何评论。

Answer 15

评论总是有用的！而且我不认为评论是浪费时间！它可以帮助其他开发人员理解您的代码，当您几个月没有处理项目时它会帮助您。

Answer 16

我曾经和你处于同样的境地。当我第一次开始时，我从来没有评论任何东西，因为一切都非常小，我总是知道它是如何工作的。但是当我继续扩展我的代码并且一切都开始指向对方时，我发现自己不知道某些事情已经发生了什么并迷失了。我不得不重写很多东西，所以我知道他们又做了什么，我开始评论所有内容，所以我确切地知道它是如何工作的以及将来如何使用它。你可能认为你现在知道一切是如何运作的，但将来你会回顾一些事情然后说'HUH？'现在最好对事情进行评论，以后可以省去麻烦。

我评论事物的方式：

始终将此添加到任何功能的顶部，以便您知道它的作用。

/**
 * What the function is supposed to do, a brief description of it.
 *
 * @param     paramter_name     Object-type     A description of it, do for each parameter.
 *
 * @return    Object-type - A brief description of what is being returned.
 **/

然后在整个代码中确保您评论看起来很复杂的内容。当您运行支票时，请添加一个快速评论，例如“确保此选项有效”。对于任何长行代码或大块代码，添加特定部分的注释，以便以后轻松找到它。

Answer 17

大学软件课程往往会让人们过度评论，以此来强迫学生对所输入的内容进行三思而后行。几年前，当我在本科课程上进行标记时，一个令人讨厌的经验法则提出了我每5-10行的评论。认为大多数Java课程都会告诉你将方法限制在大约30行，所以函数中的大量注释是你应该分解的标志。

我的个人偏好是将注释限制为记录功能目的/输入/输出和数据结构。否则，评论应该仅限于需要特别注意的事情（例如，看起来不合适的事情，或许是错误，乍一看）。

Answer 18

第一个注释是变量和方法名称。选择它们需要很多注意。如果你能想到一个更好的名字，不要犹豫，重命名它们。

一致性和惯例也有帮助。尽量避免使用NumberOfStuff，ThingCount，FooSize，总是使用相同的形式，可能与语言一致（是否有Array.length或Vector.size）。总是用相似的名字命名类似的东西。

“代码永远不会说谎。评论有时会做”。有一天，有人会修改代码而不是相关的评论。更好地花费更多时间编写自解释代码，并辅以一些聪明的评论，而不是拆分代码然后用大量注释解释事物。

Answer 19

规则＃1 评论应该表明为什么不是'什么'（代码已经告诉你'发生了什么'）

规则＃2 写完评论后 - 重写你的代码，使其像评论一样阅读（然后删除评论）

Answer 20

虽然良好的变量和函数名称等可能会减少对评论的需求，但任何足够复杂的程序仅仅通过单独查看代码就很难理解，无论它是多么仔细地编写。

通常，代码体越大，预期使用的时间越长，编写详细注释的重要性就越高。教师要求详细评论是完全合理的，因为他们不想花费大量时间来尝试理解来自不同学生的大量代码，但是你不一定要在课堂外保持相同的标准。

关于评论功能＆amp;类和类似的东西，我发现只有最琐碎的函数是如此自我解释，以至于评论不会在一段时间内挽救读者。此外，当您使用智能IDE为Java或Curl等语言编写正确格式的文档时，注释将允许开发人员只需将鼠标悬停在调用签名上即可查看函数和方法的文档。使用大型系统时，这可以为您节省大量时间。