我们不需要代码之外的文档

“你需要写更详细的文档”。你听到了没有？我听到了，很多次，在很多公司里。大多数人都会因为没有写文档而内心不安，认为应写文档。但我不是。

文档有两种——代码内和代码外。代码内文档包括javadoc(或任何用来描述类和类方法的语言工具)和代码注释。外部文档包括描述产品的文档和内部材料。

外部文档最大的问题：它会过期不更新。让它们保持同步更新是一个麻烦且耗时的工作。

外部文档第二大问题：没有人真正用它们。

程序员是写代码的。他们善于读代码。代码对于他们有特殊意义。给重要类写说明，在方法内部对重要场景写注释，这被认为是最佳编程实践方法，优秀的程序员都这么做。这能让代码对于人们来说更易理解，加上能自我说明的编码方法，这就是一部完整适用的文档。它不需要你去同步更新(你修改代码的同时修改了它)。

我们需要外部文档吗？也许吧。有必要对整个系统架构做一些简洁的描述，让这些代码有一个大的背景。有哪些模块，它们是如何交互的——这就够了，只需一页。但这同样会过期不更新，但至少它比较容易维护，团队首领和架构师需要经常的检查它们是否已经过期。

如果你是测试人员，或是产品经理，你会说你不理解这些程序，你的工作中需要这些文档。我可能有些粗鲁，但如果你需要这些东西，你应该自己去写。程序员不是技术文档撰写员，写外部文档不是他们的工作，也不是他们感兴趣的。如果你不想写这些文档，而你仍想知道这些程序是干什么的，那就去问程序员吧。他们会乐意为你读这些注释，向你解释它们的功用。如果代码的功用和期望的动作不一致时，那去检查问题跟踪系统，看看需求究竟是什么样的。你不需要外部文档来描述这些代码是干什么的。

当然，软件是给用户使用的，需要一些用户手册，但这实际应该由其他人来编写。

所以，下次当有人坚持认为程序员需要写文档来描述程序的功能时，驳斥他们。坚信这是在浪费时间和精力，坚信有了代码和注释就足够了。如果这些不够，这说明你需要有更好的编程规范和编程习惯，而不是写文档。

:)