原文大意

在实践中，注释往往是一种疫病(blight)。写好注释是一种技巧，而这个技巧在于知道什么时候不应该写注释。不正确的或者模糊的注释会混淆视听，给代码理解增加困难。有些注释在现代工程里也失去了作用，比如代码版本相关的注释不如版本控制工具的日志真实可靠。由于注释噪音太多，程序员甚至开始采取方法隐藏注释，比如将注释设成背景颜色，使用IDE插件过滤掉注释，等。

一段解释代码在做什么的注释暗示着这里需要优化代码，从而使代码本身能自描述，比如重命名类名和函数名，对长函数里提取出小的函数并通过函数名称描述代码意图，等。记得，要注释代码说不出的内容，而不是没明说的内容。

点击了解更多可看原文

叻道观点

这原文和我上篇文章的个人解读部分高度重合啊

不过，我也学到了一些小技巧：不想看注释就将注释的颜色设置成背景色，或者找一个插件在显示代码的时候过滤掉注释部分。根据这个思路，我觉得也可以将注释的字体大小改到极限小。我觉得如果这么讨厌注释，还是做一个能自动化检测的代码规范，去限制注释在代码里的比例或数目吧。

我发现这本书很多章节都只在说为什么要这样做，而不说具体怎么做到。这个章节也是如此，一直在说注释的问题，怎么避免那些写出不必要的注释，最后说了一句“只注释代码说不出的内容”，但是没说哪些是代码说不出的内容。也许是留给读者的思考吧。

我觉得，代码真正说不出的内容真的不多。

我上篇文章提过两种。

第一种是实现略复杂一些的科学运算的代码。要实现一个看得头疼的数学公式，即使你写的再简练，我认为光看代码还是会觉得很别扭的。即使写注释也不一定能直接看懂，除非使用一些为了显示数学公式的IDE插件，比如VS的TeXCommetsExtension。

source: https://github.com/kindermannhubert/VsTeXCommentsExtension

我之前也不知道这种工具。但想着这个需求应该不小于是搜索了一下，果然有人做。甚至还有输入一段科学运算公式自动生成代码的工具。

第二种是接口的契约。这里的接口是广义的概念，比如面向对象语言的接口里的方法，或者类里的公有方法等。当你提供一个接口给别人，你需要在注释里说明这个接口的契约，比如怎么使用，输入是什么，输出会是什么，会对什么情况有特殊的输出或者抛出特殊的异常，等等。

注意，这种注释是软性的契约描述，因为它不可执行，其描述可能和真实实现不一致。而硬性的接口契约应该也是存在的；我在大学的时候看过相关内容，一般以代码注解(annotation)的编程方式实现的，不过现在我还发现它被大规模使用。

即使你分享的接口和调用它的代码在一个代码工程，调用的时候看接口定义的注释还是比直接看代码实现要更容易理解如何使用。如果是通过打包的代码库提供接口，那只能依赖定义注释提供调用说明了。

我再尝试想想第三种。

也许是那些我们希望其他人重点注意的代码部分吧。毕竟有时能力不足，而且时间限制，我们总难免写出一些不太完美的代码。留个注释表示这里有些不足的地方当时先简化处理了。“人力有时尽”是个需要直面的现实问题。承认现在的不足并不是一个缺点，以后努力提高即可。

你觉得还有哪些代码是必须加注释的？

欢迎评论交流。

本系列之前的文章

#1 谨慎行事 (Act with Prudence)

#2 应用函数式编程的原则 (Apply Functional Programming Principles)

#3 问“用户会做什么？”(你并不是用户)Ask "What Would the User Do?" (You Are not the User)

#4 自动化执行你的编码规范(Automate Your Coding Standard)

#5 美在简单 (Beauty Is in Simplicity)

#6 在你重构之前 (Before You Refactor)

#7 当心共享的诱惑 (Beware the Share)

#8 童子军规则 (The Boy Scout Rule)

#9 在责备其他之前，先检查你的代码 (Check Your Code First before Looking to Blame Others)

#10 谨慎选择你的工具 (Choose Your Tools with Care)

#11 使用领域语言去编程(Code in the Language ofthe Domain)

#12 编码是设计 (Code Is Design)

#13 代码布局很重要 (Code Layout Matter)

#14 代码审核 (Code Reviews)

#15 论证式编码(Coding with Reason)

#16 对代码注释的一条意见(A Comment on Comments)