文档和注释能降低复杂度

复杂度主要是因为依赖和模糊。好的文档和注释可以澄清依赖关系，消除模糊性（填补代码语言未能妥善说明的空白）。从而降低复杂度。

写文档和注释是需要学习的

即便有人知道应该写文档和注释，但是他可能不知道如何写。不合格的注释和文档不能发挥其应有的作用，甚至会反过来影响开发工作，这也是一些人逃避写文档和注释的借口。殊不知他们提及的写文档和注释的弊端并非这件事本身而导致，而是未能正确做这件事而导致。

为啥要写注释？

用于描述无法在代码中体现的信息

如讲解某个接口应该怎么用。
为什么要做这样的设计。

对于大型项目来说，让用户通过读源码来了解如何使用相关功能是不实际的。
如果用户必须读了一个方法的源码后才能知道如何用它，那么说明这里并没有做抽象：方法中的所有复杂度都被暴露给使用者了。

如果没有注释，那么一个方法的所有抽象就是它的签名：名称+输入和输出项的类型及名称
可以通过注释对方法的使用、参数的含义和取值范围等做说明

用自然语言写成的注释本身具有更强的表现力（没有代码语言精确）。

好的注释应能反映设计者内心的一些无法通过代码实现表露的设计信息。
这可能是低级细节（如一段看似古怪的写法是为了兼容某个奇怪问题），也可能是高级概念（如总体设计思路）。当其他人（即便是开发者自己，隔一段时间后也可能是忘记当初的一些设计细节）要修改相关代码时，能协助他们更好地工作。

减少认知负荷

通过特别强调说明细节，避免开发者记在脑子里。

减少“未知的未知”这种情况的出现

通过澄清系统结构。