发布在即!企业 AIGC 应用程度测评,3 步定制专属评估报告。抢首批测评权益>>> 了解详情
写点什么

宁愿编写代码?还是把事情都写下来吧!

  • 2014-01-22
  • 本文字数:2718 字

    阅读完需:约 9 分钟

开发者真的非常讨厌花时间写东西,除非写的是代码。然而他们还对这种厌恶振振有词:

  • 如果不是代码,它就无法通过编译,也无法确定它是不是有意义。
  • 如果不是代码,它就无法执行,所以可能永远无法用于完成任何事情。
  • 如果不是代码,也就无法对它进行测试,因此也无法证明它的真实与正确。
  • 敏捷宣言中甚至都不再强调文档:可以工作的软件胜过面面俱到的文档。

那文档就一无是处吗?我想你知道答案。

为什么要写下来

很多时候,项目中的些许文档会起到很大的作用。但是要得到那些好处,开发者必须停下手中的代码,抽点时间把事情写下来。我来举一些例子,我想他们会发现文档物有所值。

记下因何而做的决定

如果项目不止持续几个月,总有这样的时候,所做的决定会改变开发过程。可能是决定使用(或明确地避免使用)某个特定的工具、框架或平台;可能是决定以某种方式编写测试,或是在某些情况下根本不编写测试;可能是决定丢掉惯常的实践方式,并且以完全不同的方式做事。这些决定将会出现,而且往往会持续下去。

在做下决定很久之后的某一天,团队里的某个人(通常是新加进来的,他们很烦人,是不是?)会问“我们为什么这么做?”。他们会得到什么样的答案呢?

如果团队里有一个人或几个人记性不错,而且这个项目他们也跟得足够久了,新的团队成员或许能得知真实原因。但是大部分情况下,恐怕答案是“因为我们总是这么做的”。谁都不想听到这样的答案。

请记住,如果碰到这样的答案,可以有所选择。你可以按照往常做事的方式继续做下去,因为你已麻木,或是因为这样做更为安全,你已经不记得开始这样做的原因了。作为选择,你可以作出改变,希望你考虑了所有可能的影响。究竟会出什么问题呢?哦,后来发现问题多的是。例如:

  • 你可能走了一条已经被探索过而且被否定了的路,浪费宝贵的项目时间和精力。
  • 你的修改可能与客户要求的系统工作方式相冲突,让客户非常懊恼。
  • 本来有所缓和的合规审查可能因为你的做事方式而破坏,并使你和 / 或你的客户遇到法律上的麻烦。

只需要花点时间把事情写下来,这些后果都可以避免。当你的团队做了会改变你工作方式的决定时,把当时的日期以及决策背后的逻辑考虑写下来。以后,当有人问起“为什么那样做”或“为什么使用那个工具”时,你就可以自信满满地回答了。

为将恼人的过程自动化做好准备

开发者经常会发现他们想将一些过程自动化。这些过程经常重复,而且会浪费宝贵的开发时间。然而,我时常碰到一些执行不那么频繁的手工过程(可能几个月一次),这些过程会涉及一系列步骤,必须按照特定的顺序完成。如果没人愿意费点力气把这个过程写下来,那就有很大的机会出现执行错误的情况,或者是执行中漏掉了某些步骤,浪费的时间甚至更多。此外,如果不先把这些步骤写下来,我们也就没有切实可行的方式将这个过程自动化。

如果你发现自己正在执行的任务有多个步骤,而且这个任务有很大的机会要再次执行,请把这些步骤写下来。当再有人必须手工执行该过程时,能够节省时间,可能有一天你终于感到非常气馁,于是你将这个过程自动化了,而今天的行动也为那一天做好了准备。

作为后手

在敏捷项目中,正如敏捷宣言所述,我们更重视面对面的交流。这样交流需求是最好的,因为不管是口头信息,还是非口头信息,都可以收集到。然而,交流的话可能被误解,更有可能被记错。任何一方都可能出现这种问题:开发者可能认为他们听到了,但是客户并没有说过,或者客户忘了(假定他们都是无意为之)他们曾让开发者选择某一特定方向。 这就致使开发者最后只是坚称某些行动是客户让他们做的,但到底是不是这样,却没有任何证据。在这种情况下,我的经验是,获胜的几乎总是客户,而开发者只能带着失意或者可能是被侮辱了的感觉走开。

看上去开发者并不希望发生这样的事。我们来看看,这种情况应该如何避免呢?我不知道……或许我们可以尝试一下把东西写下来?我们需要做的就是在电话或面对面的会议之后写封邮件,用开发者的话描述一下,在他们看来,客户让他们做哪些事。这不需要多大力气,而且当“系统为什么要那样开发”之类的问题出现时,真是很好的跟踪证据。

使编写文档容易进行的一些想法

对大部分人来说,文档并不是自然而然的;而对大部分开发者来说,文档则完全是一种痛苦。然而,上面已经解释过,文档有其价值。下面是一些让写文档不那么痛苦的想法:

  • 立即写下来。当碰到不喜欢做的事情时,我们中有很多人喜欢拖延。对于这类文档,可别这么做。最好是趁热打铁,在你不需要停下来回忆的时候写下来更容易。一谈完,就找个工作站或用移动设备把摘要写下来。
  • 借助好工具。说到移动设备,有很多极好的工具,可以用来记事。早先,即便是最简单的东西,我们也必须在 wiki 上找到一个合适的地方,并使用某些不那么直观的标记语言将它写下来。现在,我们有了无所不在的 Evernote 和 OneNote,还有很多类似的工具;还有博客和微博(在你的项目中,使用 Twitter 是不可能的吗);如果其他所有的工具都不行,还有电子邮件呢。找出你最喜欢的即可。
  • 保持简短。每次讨论的文档不需要很长。即使不能使用 Twitter,也可以假装在使用——让信息简明扼要、切中要害。在 140 个字内你能说些什么,使得描述的内容足够有用,同时又能让人快速抓住要点?文档被不止一次阅读的可能性与其长度成反比。
  • 把它记到你能再次找到的地方。如果需要的时候找不到,那记下来也没什么用。把它记在看上去最明显的位置(比如,放在建立好的项目文档仓库中,和代码放到一个地方,或者放到发给所有团队成员的电子邮件中),能以电子方式搜索的地方比较理想。不要只是将其记在团队办公区的白板上(尽管除了将其记在可以长期保存的地方,你还想使用白板)。你可能想把信息记在多个地方,看看在哪里能找到……你甚至可以就内容能够被找到的地方收集一些指标,以此来决定最好的保存位置。我知道,对某些人而言,这可能有点疯狂。

写文档需要成为习惯

正如我上面所说,将项目中日常出现的小事写成文档并不是自然而言就会去做的。你必须强迫自己这么做。我知道你宁愿编写代码,但是一定要让自己这么做;我保证物有所值。如果一有事发生,你就能让自己跳到记事系统,这很快就会成为老习惯了。那时你就会惊讶,以前不记文档是怎么过来的啊。

关于作者

Nate McKie Asynchrony 的联合创始人与 CTO。Asynchrony 是一家位于密苏里州圣路易斯市的 IT 咨询公司。 Nate 带头,使 Asynchrony 成为了敏捷技术和理念的顶级实践者。通过该公司的商业和政府客户群,他也带头传播了高质量代码和快速实现的原则。Nate 的角色是推动公司的技术方面,并将敏捷技术传授给客户。你可以在 Twitter 上关注 Asynchrony(@asynchrony)和 Nate McKie(@natemckie)。

查看英文原文: I’d Rather Be Coding – Writing Things Down

2014-01-22 06:343354
用户头像
臧秀涛 略懂技术的运营同学。

发布了 300 篇内容, 共 129.6 次阅读, 收获喜欢 34 次。

关注

评论

发布
暂无评论
发现更多内容

Android高级面试题!android享学课堂vip课程下载

android 程序员 移动开发

flutter技术解析与实战!动脑学院视频百度云

android 程序员 移动开发

英特打造通向E级计算时代“利器”,XPU架构功不可没

科技新消息

Android经典面试,享学三期Android架构师

android 程序员 移动开发

零代码的多方面解读

低代码小观

低代码 零代码 开发工具 开发平台 无代码

Android面试题及解析,android开发视频百度网盘

android 程序员 移动开发

app启动速度优化,享学课堂架构师vip

android 程序员 移动开发

handlermapping作用,扔物线朱凯

android 程序员 移动开发

Android跨进程通信导论,作为Android开发程序员

android 程序员 移动开发

android路由实现,android开发视频百度网盘

android 程序员 移动开发

边缘计算融入云计算架构的优缺点

浪潮云

云计算运维

2021年9月券商App行情刷新及交易体验评测报告

博睿数据

自定义View:布局

Changing Lin

10月月更

Android面试必刷的200道真题,全网独家首发

android 程序员 移动开发

Android面试题目,享学三期Android架构师

android 程序员 移动开发

apm性能监控系统,rxjava扔物线

android 程序员 移动开发

android设计模式工厂,动脑学院vip2019

android 程序员 移动开发

android适配器ui,享学课堂Android架构师二期

android 程序员 移动开发

Android面试必问!动脑学院vip课程分享2019

android 程序员 移动开发

GitHub标星1w的安卓架构师必备技能,腾讯T2手把手教你

android 程序员 移动开发

Android面试相关文章及Github学习资料,总结到位

android 程序员 移动开发

Android黑科技实现原理揭秘,推荐学习

android 程序员 移动开发

Android研发岗面试复盘总结,快速从入门到精通

android 程序员 移动开发

Android程序员如何有效提升学习效率,不可多得的干货

android 程序员 移动开发

android设计模式书籍,扔物线朱凯

android 程序员 移动开发

android路由跳转,动脑学院怎么样

android 程序员 移动开发

凌晨 12 点突发 Istio 生产事故!一顿操作猛如虎解决了

青云技术社区

云原生 Istio, kubenetes

Android进阶学习资料,扔物线学堂

android 程序员 移动开发

Android通用流行框架大全,大厂面试题汇总

android 程序员 移动开发

2021云栖大会,博睿数据携手阿里云共拓云原生“可观测”最佳实践

博睿数据

flutter音视频开发,动脑学院vip2019

android 程序员 移动开发

宁愿编写代码?还是把事情都写下来吧!_研发效能_Nate McKie_InfoQ精选文章