是否代码即文档优于专门写文档？刚参加工作，要用到同事(带我的师傅)写的模块

问他要文档，他说没有，说直接引入 IDE 有自动补全，随便猜猜就知道怎么用了，还告诉我这叫代码即文档，比专门写文档要好多了

请问这是业界的惯例吗
大公司里一般是这样的。

一般只有供他人调用的接口需要写文档，内部实现基本上是没有文档的，有几方面原因。

- 内部实现一般迭代比较快，写了文档很快就过时了，需要改写或者重写，时间成本比较高。

- 偏向业务的团队一般考核指标里不包含写文档，所以工程师一般没有很大的动力去写文档。

- 对于设计良好的系统，代码抽象层次清晰，命名规范，很容易通过阅读代码来理解设计思想和宏观架构。只需要在一些特殊的地方加上解释，就能够很好地用代码充当文档。

然而现实并没有那么美好。时间一长，代码的可读性会越来越差。原因如下。

- 大项目结构变得越来越复杂以后，最初的设计架构很可能已经无法支撑业务系统的规模。后续增加的模块时常充斥着各种hacking, 导致代码结构越来越混乱，也越来越不可理喻(hard to reason).

- 随着开发团队的人员流动，代码风格无法保持一致。进而导致命名不规范，使得类名、函数名不易检索(hard to grep). 

- 使用动态类型语言编写的系统，如果缺乏缺乏有效的开发环境支撑（比如Python类型注解），在规模变大以后开发效率大幅降低，各种未知的bug逐渐显现。

比较好的做法是，

- 前期的设计文档一定要认真撰写，不能为了赶时间而仓促了事。

- 各种代码规范，比如命名，代码审阅等要严格执行，而且要用程序来执行（比如linter, formatter)，不能只依靠人的自觉。类型标注里禁止使用any等。

- 提高测试覆盖率。很多时候API的单元测试可以充当非常好的文档，展现了各种正确的和不正确的用法。