Comment Only What the Code Cannot Say 17

Comment Only What the Code Cannot Say

仅注释代码里没有交代的内容

Comment Only What the Code Cannot Say · 97 Things Every Programmer Should Knowhttps://97-things-every-x-should-know.gitbooks.io/97-things-every-programmer-should-know/content/en/thing_17/

The difference between theory and practice is greater in practice than it is in theory — an observation that certainly applies to comments. In theory, the general idea of commenting code sounds like a worthy one: Offer the reader detail, an explanation of what's going on. What could be more helpful than being helpful? In practice, however, comments often become a blight. As with any other form of writing, there is a skill to writing good comments. Much of the skill is in knowing when not to write them.

When code is ill-formed, compilers, interpreters, and other tools will be sure to object. If the code is in some way functionally incorrect, reviews, static analysis, tests, and day-to-day use in a production environment will flush most bugs out. But what about comments? In The Elements of Programming Style Kernighan and Plauger noted that "a comment is of zero (or negative) value if it is wrong." And yet such comments often litter and survive in a code base in a way that coding errors never could. They provide a constant source of distraction and misinformation, a subtle but constant drag on a programmer's thinking.

What of comments that are not technically wrong, but add no value to the code? Such comments are noise. Comments that parrot the code offer nothing extra to the reader — stating something once in code and again in natural language does not make it any truer or more real. Commented-out code is not executable code, so it has no useful effect for either reader or runtime. It also becomes stale very quickly. Version-related comments and commented-out code try to address questions of versioning and history. These questions have already been answered (far more effectively) by version control tools.

A prevalence of noisy comments and incorrect comments in a code base encourage programmers to ignore all comments, either by skipping past them or by taking active measures to hide them. Programmers are resourceful and will route around anything perceived to be damage: folding comments up; switching coloring scheme so that comments and the background are the same color; scripting to filter out comments. To save a code base from such misapplications of programmer ingenuity, and to reduce the risk of overlooking any comments of genuine value, comments should be treated as if they were code. Each comment should add some value for the reader, otherwise it is waste that should be removed or rewritten.

What then qualifies as value? Comments should say something code does not and cannot say. A comment explaining what a piece of code should already say is an invitation to change code structure or coding conventions so the code speaks for itself. Instead of compensating for poor method or class names, rename them. Instead of commenting sections in long functions, extract smaller functions whose names capture the former sections' intent. Try to express as much as possible through code. Any shortfall between what you can express in code and what you would like to express in total becomes a plausible candidate for a useful comment. Comment what the code cannot say, not simply what it does not say.

By Kevlin Henney

​
理论和实践之间的差异在实践中比在理论上更大——这一观察结果当然适用于评论。理论上，注释代码的总体思路听起来很有价值：向读者提供详细信息，解释正在发生的事情。还有什么比提供帮助更有用的呢？然而，在实践中，评论往往会成为一种祸害。与任何其他形式的写作一样，写好评论也是有技巧的。大部分技巧在于知道什么时候不该写。
当代码格式不正确时，编译器、解释器和其他工具一定会反对。如果代码在某种程度上功能不正确，那么评审、静态分析、测试和生产环境中的日常使用将清除大多数错误。但评论呢？Kernighan和Plauger在《编程风格的元素》中指出，“如果注释是错误的，那么它的值为零（或负值）。”然而，这样的注释往往以编码错误永远无法做到的方式在代码库中随处可见。它们提供了持续的分心和错误信息来源，对程序员的思维产生了微妙但持续的拖累。
那些在技术上没有错误，但对代码没有任何价值的注释呢？这样的评论是噪音。鹦鹉学舌地模仿代码的评论并没有给读者带来任何额外的东西——在代码中一次又一次地用自然语言陈述一些东西并不会让它变得更真实或更真实。注释掉的代码不是可执行代码，因此它对读取器或运行时都没有任何有用的效果。它也很快变得陈腐。与版本相关的注释和注释掉的代码试图解决版本控制和历史记录的问题。版本控制工具已经（更有效地）回答了这些问题。
代码库中充斥着嘈杂的注释和不正确的注释，这鼓励程序员忽略所有注释，要么跳过它们，要么采取积极措施隐藏它们。程序员足智多谋，会绕过任何被认为是有害的东西：折叠评论；切换着色方案，使得注释和背景是相同的颜色；编写脚本以过滤掉评论。为了使代码库免受程序员独创性的误用，并降低忽略任何真正有价值的注释的风险，注释应该被视为代码。每一条评论都应该为读者增加一些价值，否则就是浪费，应该删除或重写。
那么什么才算是价值呢？注释应该说明代码没有也不能说明的内容。解释一段代码应该说什么的注释是对更改代码结构或编码约定的邀请，这样代码就不言自明了。与其补偿糟糕的方法或类名，不如重命名它们。不要在长函数中注释部分，而是提取较小的函数，这些函数的名称反映了前一部分的意图。尽量通过代码来表达。您可以在代码中表达的内容和您想要表达的内容之间的任何不足都会成为有用评论的合理候选者。注释代码不能说的内容，而不仅仅是它没有说的内容。
作者：Kevlin Henney
​