logo标签列表

什么情况下评论“过多”，什么情况下又“不足够”？

commentscoding-style
29

我所在的公司正在进行一场关于代码中注释有效性的小型辩论。其中一位领导指示开发人员不要使用注释，因为他们觉得注释使用“过时”，而其他几位开发人员则表示他们从不使用注释，因为他们认为这只会使代码变得混乱。

我一直遵循的做法是，在每个文件的顶部使用基本注释块进行注释，并对每个方法/类/等定义进行注释，然后在代码中任何我认为6个月后可能回来并想“WTF”的地方进行注释。

显然，这是主观的，但我很想知道有没有人有什么好的争论或经验，支持一种或另一种方式。

在我工作的地方，我们被建议不要在代码内部使用注释，除了TODO注释。这有助于编写清晰的代码。 - Alexandre C.
3
我认为这并不能帮助编写清晰的代码，只会让别人不清晰的代码变成一堆无意义的话。注释的有无并不会改变代码本身。 - Joel Etherton
@Joel：这样做的理由是函数名和代码结构应该使注释变得无用。 - Alexandre C.
2
我可能会在6个月后回来，然后想：“WTF”。这很可能表明代码不够描述性，需要重构。这只是一个经验法则，而不是教条，但对于我的代码来说，如果我认为将来可能会感到“WTF”，那么公司中的其他人现在也会有同样的想法。再次强调，这就是我进行重构的地方。 - Jamie Dixon
@Jamie Dixon - 确实如此，但我曾经遇到过这样的例子，代码之所以那么混乱，仅仅是因为它完全按照业务需求编写（通常是财务计算），而没有在我面前看到需求，有时候当我再次查看时，计算会让我感到困扰。当面对这种情况时，我的另一个不良习惯是写下要求文档、章节等的名称，以便我至少知道在哪里可以再次查找它。 - Joel Etherton
2
许多重复的问题：http://stackoverflow.com/questions/36432/commenting-code，http://stackoverflow.com/questions/20922/do-you-comment-your-code，http://stackoverflow.com/questions/163600/when-not-to-comment-code，http://stackoverflow.com/questions/111563/whats-the-golden-code-comment-ratio等。 - gnovice
9个回答
26
感谢您提供的链接文章，阅读起来很有收获。 - Joel Etherton
@Joel - 没关系，Jeff非常好地总结了问题。 - Yuval Adam
10
他用平方根的例子削弱了自己的观点；当他将其改为“自描述代码”的风格时，失去了牛顿-拉夫逊逼近算法的信息。良好的标识符和注释需要相互协作。 - Russell Borogove
这个主题的更好的文章来自Steve Yegge：http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.html - matt b
25
在我的整个职业生涯中，我从未遇到过那种神奇的“自文档化代码”。也许我只是运气不好，但我开始怀疑它是否真的存在。
1
我在2012年看到过这样的代码。当时我正在Atlassian公司工作，负责核心平台代码，我想：“哇，我喜欢这个代码，但是那个架构师没有在代码中加注释，可能是因为他利用了自己的资历来...避免遵守指南之类的吧？但我知道它是如何工作的，所以也许我和他一样是一个黑客。”然后原因就清楚了：方法名称正确，变量自说明，代码路径简单。我只是不知道需要多少经验才能达到同样的简洁性。 - Adrien
16

偶尔我会遇到一些代码，它的分区非常优雅，方法、字段和变量的名称非常明显，从代码中我需要知道的一切都很明显。

一般情况下，只有真正伟大的代码大师才能写出这样的代码。我们其余人都是拼凑出能用的东西。

  • 如果你是一个真正伟大的代码大师，请不要用多余的注释玷污你神圣的代码。
  • 如果你几乎不知道自己在做什么，请小心记录下你的尝试失误，这样别人就可以试图挽救这个混乱。
  • 如果你是普通人（大多数人都是这样，基本上是定义），请在注释中留下一些提示，使维护时更容易，但不要侮辱任何人的智商并浪费空间来记录那些非常明显的内容。理想情况下，您的注释应该描述您的代码在元级别上的内容，指示您正在做什么，而不是为什么。同时，如果您正在进行异常或棘手的操作，还应包括如何实现。
7
这段话的意思是：这种无能力的人最重要的特征之一就是他们无法意识到自己的无能。如果他们有这样的认识，那么就已经解决了一大部分问题。 - sarnold
Kruger-Dunning！我正在寻找它。@sarnold：谢谢！ :) - Carl Smotricz
@Carl - 我想问一个不同的问题，你是否曾经发现自己为最低公共分母进行评论？在你看来，一个团队应该在什么“元级别”上对代码进行评论？ - Joel Etherton
1
@Joel：我尝试在“中间”一直进行注释。我的注释解释了整体方法和任何不明显的内容（或需要挖掘其他资源等）。我还会对字段进行注释（但不包括getter/setter！），其中名称并不能明确显示其中的内容。 - Carl Smotricz
1
这是有一定道理的，但阿喀琉斯之踵在于没有人能够准确评估自己的技能水平。 - DarenW
7

其中一位主管指示他的开发人员不要使用注释，因为它们太“老套了”，另外几位开发人员表示他们从不使用注释，因为他们认为注释只会使代码变得混乱。

如果我听到与我合作的开发人员说这样的话，我会纠正他们。如果我没有足够的权力来纠正他们，我会离开这份工作。

良好命名和清晰易懂的代码 - 有时称为“自说明”的内容 - 可以很好地说明代码正在做什么。这在某种程度上是可以接受的。注释的作用是解释为什么。

幸运的是，我没有在这些开发人员的任何一个部门工作。在我们的团队中，第一件事就是定义我们的代码项目标准文档（包括注释）。对于我们的标准文档的非正式讨论是引起两个小组之间辩论的原因。 - Joel Etherton
5

这个话题经常被讨论，但是我对此有一些看法：

  1. 我宁愿看到过多的注释而不是没有。如果代码中没有注释，那么你无法从中获取任何意义；但是如果注释太多，你可以随时将其从代码中删除。
  2. 我听说有些开发者认为，过度记录（每个人对此的定义都不同）代码的开发者并不是好的开发者。虽然说你正在更新计数器可能表明你不知道自己在做什么，但是在你正在工作的方法中清晰地指导一些业务逻辑可能会非常有用。
  3. 虽然有一些出色的开发者能够编写极为清晰的代码，不需要注释，但大多数开发者并不如此优秀，或者他们花费了更多时间来编写自文档化的代码，而如果他们只是包含了几个注释，他们的效率会更高。
  4. 你不知道下一个阅读你代码的人的技能水平，如果你使用的语言结构可能会使人困惑，通常最好包含一条注释，以便其他人可以用来搜索教程。
3

注释的问题在于，它们往往会留在被注释的代码已经更改甚至被删除之后。

一般来说，我只会对公共API和难以理解的算法进行注释。

不要使用注释来解释你做了什么 - 这就是代码的作用，使用注释来解释为什么这样做。

1
强烈建议使用具有拼写检查功能的工具编写您的回复。 - sarnold
不要使用注释来解释你做了什么，这就像《银河系漫游指南》中的未来将会成为过去时态之一。 - Mr. Boy
@sarnold，SO编辑器为我进行了拼写检查，也许他没有注意到红色下划线？ - John La Rooy
我对这篇文章感到同情，于是修正了语言。 - Carl Smotricz
@carl Smotricz，我没有注意到“编辑”链接，谢谢；我对这篇帖子心生怜悯，修复了这个错误的习语。 :) - sarnold
1

Diomidis Spinellis刚为IEEE专栏（在他的博客上引用）撰写了一篇不错的专栏，概述了这个问题以及几种解决方案：

当我们进行评论时，离灾难只有几个按键的距离：用英语重新表述代码的功能。而那时问题就开始了。

0
一个人应该在代码或函数之前编写注释，这样下次查看该函数时，他/她可以立即知道该代码的目的。
很多时候我会写代码，然后忘记了它的目的。因此，我养成了在代码之前编写注释的习惯。
0
我希望在评论中看到的是一个解释，为什么一个比代码中使用的方法明显且简单得多的方法不起作用。
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接