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

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

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

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

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

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

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

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

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

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

网站标题：我们不需要代码之外的文档
URL网址：http://www.hantingmc.com/qtweb/news45/458845.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联