首页»观点评论»我们不需要代码之外的文档

博悦平台登录: 我们不需要代码之外的文档

来源:aqee 发布时间:2013-07-18 阅读次数:

博悦娱乐测试地址

思政工作者要敢于直面、回应现实矛盾和问题,挖掘富有时代感的鲜活素材,善于用年轻人的语言表达方式和新媒体技术手段,将精妙的理论转化为浅显易懂的“家常话”,把“高大上”的思想变得平易近人,让学生们从情感中去领悟和品尝深层次的道理,在互动对话中廓清思想迷雾、拉直心中问号。古语有云:世事如棋;我们要说:棋如世事。

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

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

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

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

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

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

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

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

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

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

QQ群:WEB博悦娱乐官方群(515171538),验证消息:10000
微信群:加小编微信 849023636 邀请您加入,验证消息:10000
提示:更多精彩内容关注微信公众号:全栈博悦娱乐中心(fsder-com)
网友评论(共0条评论) 正在载入评论......
理智评论文明上网,拒绝恶意谩骂 发表评论 / 共0条评论
登录会员中心