“好代码本身就是最好的文档。当你需要添加一个注释时，你应该考虑如何修改代码才能不需要注释。” 这是 Steve McConnell 说的。同样，大部分人都不知道，或者忘掉后面半句：Good code is its own best documentation. As you’re about to add a comment, ask yourself, “How can I improve the code so that this comment isn’t needed?” Improve the code and then document it to make it even clearer. 如果你是程序员，回想一下多少次跟别人讨论代码是不是必须要注释时，这句话被引用到；有很多次在写代码时喜爱这句话，又多少次改别人的代码时痛恨这句话。
还是从我个人的观察来看，对很多程序员来说，其编码能力还不足以达到“代码本身就是最好的文档”的地步，包括我自己。敝司招聘过很多顶尖的工程师，有传说中的各种杰出前辈，可能在各种学校、公司内部事迹广为流传。但若是你哪天继承了他的代码遗产，就会发现很多传说中的明星跌落凡尘。成百上千行没有注释，使用一个公共库函数时要么接口就根本没注释只能基本靠猜，要么即使注释也语焉不详让你踩到未注明的大坑。每到这个时候你心里总会暗暗骂娘，后面别人再谈到他的光辉事迹时，你跟随讪笑时心中暗自腹诽：“牛逼个锤子！”
但我想很多人争论的焦点是：“注释是不是不可省略的、要强制执行的？”即使个别人能力真能达到“代码本身就是最好的文档”的地步（我还没见过），我也不建议在团队中传播“注释可以省略”这一想法。因为如果你说“注释可以省略”，可能你会发现大家都理解和实践成“终于可以不写注释了”。如果一个刚刚大学毕业、脑袋里从来没有过 documentation 概念、从来没写过注释的新人进入公司，就“终于可以不写注释了”，那么我想他的代码会很难达到“代码本身就是最好的文档”这个级别。因为他根本没有机会懂得什么叫做 documentation。
在公司里，代码注释深远地影响着团队合作的每个人，以及软件生存期里所有的维护者，甚至会影响自己的职业声誉。所以无论别人怎么想，我对注释这个问题的答案始终是：“注释是不可省略的，越完善越好的，甚至强制执行矫枉过正也没关系的！”
对于个人而言，“好代码就是好文档”也是一句空话，不信的话，你半年后再来看看自己半年前写的没有注释和文档的代码，你肯定会发出感慨：“这写的是什么玩意？！”
参考
https://yangwenbo.com/articles/words-that-make-code-bad.html