标签： 编程定律、原则或模式

“好代码本身就是最好的文档。当你需要添加一个注释时，你应该考虑如何修改代码才能不需要注释。” 这是 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

复杂度只会转移不会消失。

现实世界中的业务的复杂度是守恒的，不是说你软件代码的设计模式用得好就能解决业务的复杂度（在软件层面，解决业务问题的是算法和数据结构，而不是软件设计，软件设计得好只是能方便代码复用、提高运维效率罢了）。

真正能减少软件层面的业务复杂度的是，高效的管理及精简业务的流程。

软件不能解决管理问题，只能在流程上提高效率。因为软件只是工具，需要人去使用、去执行。企图开发一个软件来解决管理问题的人，是本末倒置，是懒，正确的思路应该是：管理制度及其流程已经设计好了，开发一个软件来提高执行流程的效率。

另请参见复杂性守恒定律 (The Law of Conservation of Complexity or Tesler’s Law)。