Language agnostic 评论实践？

作为一名计算机工程专业的学生，我一直受到压力，要为我所做的每一件事打上非常详细的评论。我认为这对小组项目或工作场所非常有用，但当你在自己的项目上工作时，你会花同样多的时间来评论吗

作为一个个人项目，我正在做的越来越复杂，我有时觉得我应该多加评论，但我也觉得这是浪费时间，因为我可能是唯一一个在做这个项目的人。花这么多时间和凌乱的代码值得吗

想法

---

编辑：这给了我很多思考。谢谢大家的意见！我从没想到会有这么大的反应

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

当代码无法解释时，经过深思熟虑的注释就会说明问题。经过深思熟虑的函数和变量名消除了对大量注释的需要。如果你觉得有必要评论所有的内容，请考虑简化你的代码。 如果你决定公开你的个人项目，人们会感谢你的评论（除非他们很糟糕）。如果你突然想到了一个非常好的想法，你的个人项目变成了一项业务，那么你将雇佣更多的开发人员，你的评论也会很有价值。如果你头部受了轻微的伤害，那么当你回到工作岗位时，你会感谢你的评论。

我过去的处境与你完全一样。当我刚开始的时候，我从来没有评论过任何东西，因为所有的东西都非常小，我总是知道它是如何工作的。但是当我继续扩展我的代码，所有的东西都开始指向对方时，我发现自己不再知道某些东西做了什么，于是迷失了方向。我不得不重写很多东西，所以我知道他们又做了什么，我开始评论每件事，这样我就确切地知道它是如何工作的，以及将来如何使用它。你可能认为你现在知道一切是如何运作的，但将来你会回顾一些事情并说‘嗯？’，最好现在就评论一些事情，避免以后的麻烦

我评论事物的方式：

始终在任何函数的顶部添加此项，以便您知道它的作用

/**
 * 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.
 **/

---

然后在整个代码中，确保注释看起来复杂的内容。当你运行检查时，放一个类似“确保这是有效的”的快速注释。对于任何长代码行或大代码块，请添加该特定部分的注释，以便以后轻松查找。

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

评论——或者更好的是，重新编码——任何现在不明显的东西。稍后它将是完全不明显的。你可能会想，“但这将是我，”但是如果你的思维方式（和编码方式）随着你的成长而改变那么现在对你来说显而易见的可能以后对你来说就不那么明显了。

有些人将注释视为一种代码气味，这表明代码可以使用更具描述性的名称和更好的结构。他们将修复代码，使其不需要注释

这在很多情况下都有效。然而，一种有用的评论类型是“为什么”正在做某事。有时，修复是出于一些模糊的原因而进行的，这些原因在以后查看代码时并不明显。注释不应该表达代码的功能（命名应该包括这些功能）或它是如何实现的（同样，代码会告诉您这一点），所以请将注释保存为“为什么”

---

我发现没有什么比单元测试更好的文档说明了一些东西是如何工作的。

如果代码编写得很好，方法很短（参见模式），那么代码只需要很少的注释。只有解释“为什么”的注释才是有用的——解释“什么”的注释应该被改进代码所取代，这样代码的功能就显而易见了。注释不应用于编写错误代码

公共API，尤其是在封闭源代码的应用程序中，可能是唯一推荐使用完整Javadoc的地方——然后您需要努力维护它们，并使它们始终保持准确和最新。误导性或过时的评论比没有评论更糟糕。最好通过为代码编写测试并使用

---

这本书有一个关于注释的好章节。

单元测试等是最好的代码文档形式。一些测试框架编写了被测试类应该做什么的规范，用纯英语向人们介绍了一段代码是如何工作的，同时也提供了非常简洁的方法来实现测试本身

例如Scala的ScalaTest或Ruby的RSpec

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

记住，有过时注释的代码比没有注释更糟糕

很多时候，注释只是说明代码到底做了什么，这是在浪费人力。如果没有，你的代码可能很糟糕，你应该重构它

---

只需使用测试框架。

您已经阅读了完整的代码了吗？推荐作为一个非常好的阅读，并且是一个很好的方法来了解CS profs深入您的喉咙的一些事情

代码注释有两种类型：

注释解释逻辑，使 确保代码与 意图人们通常会写得很高 级别的伪代码，并将使用它 在评论表中填写

// add 1 to i
++i;

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

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