您当前的位置:偶偶电脑知识网 -> 电脑初学 -> 电脑内容-> 我们不需要代码之外的文档

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

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

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

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

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

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

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

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

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

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

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