谷歌的软件工程 读书笔记（十）文档

码农的两大烦恼：

1. 别人的代码没有文档
2. 别人居然要求我给我的代码写文档

文档的质量差，数量少，甚至根本没有文档是软件工程面临的普遍问题。

什么是合格的文档？

任何对于代码的补充性文本都是文档，包括代码的注释。

为什么需要文档？

码农对于文档的轻视除了不能带来短期收益外，还有如下的原因：

好的文档收益如下：

文档就像代码

文档和代码一样，需要保持清晰，准确，一致，避免出错。文档需要有维护者和所有者。

谷歌使用go/links来使文档的访问变得简单。

文档和代码仅仅的耦合，所以应该被看作是代码的一部分。

文档应该：

了解你的读者

工程师写文档犯下的最大的错误就是以为文档是写给自己看的。记住写文档的时候要清楚的了解谁才是这个文档的读者。不一定要写出完美无暇的文档们，但是要写出适合读者阅读的文档。

需要考虑读者的不同方面

文档的类型

文档的类型包含：

文档的审视

文档和代码一样，需要审视。

文档的审视需要考虑以下的内容：

写文档的哲学

总结

和测试相比较，文档在谷歌受到的重视程度还是要低一些。测试可以自动化，而文档不可以。