11

我一直讨厌用星号填满一半屏幕的评论，只是为了告诉你该函数返回一个字符串，我从未读过这些评论。

但是，我确实阅读了描述为什么完成某事以及如何完成的注释（通常是代码中的单行注释）；当试图理解别人的代码时，这些非常方便。

但是在写评论的时候，我不这么写，而是我只在编程比赛写算法的时候才用评论，我会想到算法会怎么做，然后我会把每一个都写在一个注释，然后编写与该注释对应的代码。

一个例子是：

//loop though all the names from n to j - 1

除此之外，我无法想象为什么有人会在可以编写代码的时候浪费宝贵的时间来写评论。

我是对还是错？我错过了什么吗？我不知道还有哪些其他好的评论用例？

4

11 回答 11

17

评论应该表达你为什么在做某事而不是你在做什么

于 2010-02-09T19:28:56.933 回答
6

这是一句古老的格言，但一个很好的指标是：

评论你为什么做某事，而不是你如何做。

说“循环遍历从 n 到 j-1 的所有名称”即使是新手程序员也应该从代码中立即清楚。给出你这样做的原因有助于提高可读性。

于 2010-02-09T19:30:01.220 回答
5

如果您使用Doxygen之类的东西，您可以完整记录您的返回类型、参数等，并生成一个不错的“源代码手册”。我经常为客户这样做，以便继承我的代码的团队不会完全丢失（或被迫审查每个标题）。

文档块经常被过度使用，尤其是强类型语言。使用 Python 或 PHP 之类的东西比 C++ 或 Java 更冗长更有意义。也就是说，对于不能自我解释的方法和成员（例如，未命名的更新），这样做仍然很好。

如果我是第一次阅读我的代码，只需评论一下我想告诉自己的内容，我就节省了很多小时的思考时间。更多的叙述和更少的观察。评论不仅应该帮助别人，也应该帮助你自己……尤其是如果你五年没有碰过它的话。我有一些我写的十年前的 Perl，但我仍然不知道它有什么作用。

我在 PHP 和 Python 中做过的一件非常肮脏的事情是使用反射来检索用户界面中的注释块和标签元素。这是一个用例，虽然很讨厌。

如果使用错误跟踪器，我还会将错误 ID 放在我的更改附近，以便我有对跟踪器的引用。这是对更改的简要描述（内联更改日志）的补充。

当我在做我的同事很少看到的事情时……或者当微妙很重要时，我也违反了“只评论为什么不做什么”的规则。例如：


for (int i = 50; i--; ) cout << i; // looping from 49..0 in reverse
for (int i = 50; --i; ) cout << i; // looping from 49..1 in reverse
于 2010-02-09T19:31:32.433 回答
4

我在以下情况下使用注释：

  1. 高级 API 文档注释，即这个类或函数的用途是什么？
  2. 评论“为什么”。
  3. 对更长的代码块所做的简短的高级摘要。这里的关键词是summary。如果有人想要更多细节，代码应该足够清晰，以便他们可以从代码中获取。这里的重点是让浏览代码的人可以轻松找出某些逻辑的位置，而无需深入了解其执行方式的细节。理想情况下，这些情况应该被分解成单独的函数，但有时它只是不可行，因为该函数将有 15 个参数和/或不可命名。
  4. 如果你真的很注意，指出阅读代码时可以看到的细微之处，但不要像考虑到它们的重要性那样突出它们。
  5. 当我有充分的理由需要以骇人听闻的方式（性能等）做某事并且不能更清楚地编写代码而不是使用注释时。
于 2010-02-09T20:01:26.087 回答
2

注释掉所有你认为不简单的东西，下次看到你的代码时你将无法理解。

于 2010-02-09T19:38:06.440 回答
1

记录您认为您的代码应该实现的目标并不是一个坏主意（特别是如果代码不直观，如果您想将注释保持在最低限度），以便以后阅读它的人可以更轻松地调试/错误修复。尽管在阅读别人的代码时遇到的最令人沮丧的事情之一是代码已更新，但注释却没有....

于 2010-02-09T19:30:02.013 回答
0

我一直讨厌用星号填满一半屏幕的评论，只是为了告诉你该函数返回一个字符串，我从未读过这些评论。

在这种情况下，一些注释通常不具有那么极端的格式，实际上存在以帮助 JavaDoc 和 Doxygen 等工具为您的代码生成文档。我认为这是一种很好的注释形式，因为它具有人类和机器可读的文档格式（因此机器可以将其翻译成其他更有用的格式，如 HTML），使文档接近代码它记录（以便如果代码发生更改，文档更有可能更新以反映这些更改），并且通常会为大型代码库的新手提供一个很好的（和直接的）解释，说明为什么存在特定功能。

否则，我同意所有其他陈述。评论原因，仅在不明显时评论。除了 Doxygen 注释，我的代码通常很少有注释。

于 2010-02-09T19:33:17.670 回答
0

另一种通常无用的评论是：

// Commented out by Lumpy Cheetosian on 1/17/2009

...呃，好吧，源代码控制系统会告诉我的。它不会告诉我的是为什么 Lumpy 注释掉了这段看似必要的代码。由于 Lumpy 位于 Elbonia，所以我要等到星期一他们都从 Snerkrump 假日节回来时才能知道。

考虑您的听众，并降低噪音水平。如果您的评论包含太多无关紧要的废话，开发人员在实践中只会忽略它们。

顺便说一句：Javadoc（或Doxygen或等价物）是一件好事（tm），恕我直言。

于 2010-02-09T19:44:16.740 回答
0

我还使用注释来记录特定需求的来源。这样，开发人员以后可以查看导致代码保持原样的需求，并且如果新需求与其他需求冲突，则在破坏现有流程之前解决该问题。在我工作的地方，要求通常来自不同的群体，他们可能不知道其他要求，那么系统必须满足。我们也经常被问到为什么我们以某种方式为特定客户做某件事，这有助于研究了解我们的跟踪系统中的哪些请求导致代码成为它的样子。这也可以通过将代码保存在源控制系统中来完成，但我认为这些注释也是注释。

于 2010-02-09T19:55:46.363 回答
0

提醒我

真正的程序员不写文档

于 2010-02-09T21:03:39.383 回答
0

我不久前写了这个评论，从那以后它为我节省了几个小时：

// NOTE: the close-bracket above is NOT the class Items.
// There are multiple classes in this file.
// I've already wasted lots of time wondering,
// "why does this new method I added at the end of the class not exist?".
于 2010-09-28T09:11:44.553 回答