代码就是文档？
我刚上班的时候，coding总是追求写的很完美，逐行逐字地反复优化，一个变量名都要斟酌半天。那会我会经常搜索一些如何将代码写得好的文章和教程，总会在里面看到这样一句话：代码就是文档。我信了。
现在我工作接近七年了，今天在一个社区看到有人问出了一个这样的问题，和我几年前看的文档内容是一样的：
“代码就是文档”—— 这个观点是哪里有不对的地方呢？ 我目前就是想着写代码应该朝这个方向努力，觉得代码应该尽力做到易读，就是像一份文档一样，代码中也不需要加过多的注释。
几年前的我或许会不假思索的在这位兄弟的评论区，洋洋洒洒的夸赞代码就是文档的观点，不过我当看到这个问题的时候，我的脑袋里冒出来的不是对这个观点的赞许，而是辩证的批判。
从结构上来看，代码就是文档这句话一点毛病没有，coding的目标之一就是要求极高的可读性。什么是文档？文档无非就是承载了一些信息的可读物罢了。注意，是可读物，图片也是可读物，表格也是可读物。从文档的本质来看，代码的一个功能就是给开发阅读，从这个角度看，代码就是文档。
那这句话有什么问题呢？他有一个隐含的意思，很多人读这句话读出来的意思是“代码就是全部文档”，这就不对了。
代码就是文档
先讲讲这句话对的部分吧。
代码首先是开发人员能接触到的软件运行的最详细的和最准确的流程信息，除非为了定位特定问题，否则很少有人会去看软件实际的cpu指令的，从这个角度看，代码是面向第一开发者提供的关于软件的唯一真相源。if flag > 10 就必须是跟10比，必须是大于，没有歧义，也不存在笔误，这是代码最重要的优势——准确性。
所以如果一个开发人员想知道整个模块中流程的处理，包括每一个参数的操作判断和流动的情况，他能看的只有代码，而且代码会给他他想知道的一切。所以对于开发来说，代码就是文档，这句话完全正确。
谁在读代码？
这句话不对的部分，可以通过小标题联想出来。谁在读代码？
首先我们看看，标准的软件开发的文档，是有哪些人阅读的，以及他们想要获得的信息是什么。
- 本模块开发，需要获得最完整的信息。
- 测试，需要知道输入与输出的关联，即我输入什么会输出什么，不关心中间细节。
- 产品经理，需要知道功能和用户体验。
- 架构师，需要知道所有模块之间的关系，整体的分布。
- 其他模块开发，需要知道这个模块对外暴露的接口，以及这些接口的作用和输入输出信息。
这些人，谁会去读这块代码？——只有本模块的开发。其实从上面列的角色，我想表达的内容就很清晰了。
文档的作用是信息的展现，信息的展现需要高效/准确。代码确实有着最完整和最准确的信息，从准确的角度来讲，代码能满足要求。但代码所囊括的信息太全了，反而会带来极高的认知负荷，换句话说，代码作为文档没有做到高效性。
软件设计业界常用的框架之一，就是4+1视图。逻辑视图负责系统的逻辑层解释；开发视图是讲代码的结构和分层；进程视图是看进程的划分/交互和信息交换；物理视图是看部署在哪；功能视图则是最面向用户的说明这个系统是干啥用的以及怎么用的。为什么需要4+1视图？因为要获得不同的信息，需要有不同的角度。4+1视图真正落地的其实只有一样东西——代码，但为了高效的针对不同特定视角，才催生出了这些不同的视图。
前面我说代码做不到高效性，从设计人员的角度看，做不到高效性，无法把无关信息折叠起来，会造成大量的认知负荷。造成认知负荷就让我们无法聚焦重点——不同的问题会有不同的重点，从而更容易出纰漏。
信息黑洞
代码提供的信息是完整的，但这个完整仅限于运行和当前结构的完整，有些信息是不会成为代码，从而也无法从代码中再提取出来的。
比如友商方案的洞察对比，比如需求提出的背景，比如一些踩坑的复盘导致的某个参数的修改（或许有人说，我可以在代码中解释原因，我想反驳的不是不能放代码里，二是没法全部放在代码里）。
为什么有人会觉得代码就是一切？
一个是傲慢。阅读代码是开发的能力，不是所有人的能力。开发自吹代码能解释一切，他们没考虑到很多人读不懂代码，或不需要读懂代码。
另一个是偷懒。想用代码就是文档的蹩脚理由，来逃避写文档。
第三个是无知。只从自己的角度看问题，不从别人的角度看问题，不是蠢就是坏。——几年前的我就是这样，我有理由相信，我在其他的问题上还是蠢。
总结
代码是文档，但代码不是所有的文档。
实际操作中，即便是项目背景，技术洞察对比，也可以放到代码里。但我们是人，不是电脑。在没有人只有电脑的世界，“代码就是全部的文档”这句话说不定是真的。