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

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

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

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

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

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

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

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

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

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

[英文原文:We Don’t Need That Documentation ]

分享这篇文章:

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

  1. 独行猫儿 says:

    写了一个程序,除了源码里写着每个模块是干什么的,其他的文档一概不写。谁他娘的知道你做的是什么玩艺,是自动会生成新bug的垃圾文件生成器还是可以随时使系统crash的定时炸弹?

    • haohao says:

      有没有外部文档跟软件是“自动会生成新bug的垃圾文件生成器还是可以随时使系统crash的定时炸弹”是完全没有任何关系的。你想想,开发文档里面怎么可能会描述自己的bug呢。导致crash的bug只会隐藏在代码里面,不运行的话就只有看代码才有可能找到,你举的例子是在打自己的脸。

      • Gavin says:

        同意,代码是最好的文档,我们需要提高我们的编码规范和代码注释,外部文档简单描述一下大体框架就可以了,我是程序员,我为自己代言,哈哈哈

  2. haha says:

    哈哈我就在写文档,被逼的,没办法,总得给老板演示,人家要看文档

  3. 刘华 says:

    代码只是设计的一种实现形式,描述的内容非常有限。我觉得设计层面的文档还是必不可少的。

  4. feinfo says:

    文档在很多时候还是很有用的

  5. qefee says:

    为了后来的程序猿,还是写点吧,O(∩_∩)O哈哈哈~

  6. laurenceyu says:

    “坚信这是在浪费时间和精力,坚信有了代码和注释就足够了。如果这些不够,这说明你需要有更好的编程规范和编程习惯,而不是写文档。”
    前提很明了了,程序员水平高,leader管理能力强,才能达到如此完美的境界。

  7. andyf says:

    对于复杂的业务流程,一个流程图是非常有用的。
    看代码会看死人。

  8. Frank_Han 对这篇文章的反应是赞一个

发表评论

电子邮件地址不会被公开。 必填项已用*标注