为什么需要提前撰写Spec文档
Joel on Software(中文名叫《Joel软件随想录》)算得上是一本旧书了,但里面的建议和讨论,真的是历久弥新。特别是,Joel是个有趣、牛逼的家伙:前微软Excel的职员、Stack Overflow的创始人、Trello的创始人,以及他和他的boyfriend走入了婚姻殿堂。这本书,是Joel自己blog文章的一个精选集。
Joel在这本书里谈到了很多技术性的观点,高屋建瓴地从思想方法上去讨论如何看待程序、看待公司、看待构建过程。著名的The Joel Test也出自于此。
这本书我很早就知道,但一直没有机会亲自阅读。最近读了几章,便爱不释手。按理说,我应该将这本书读完后再写点评论。可是,它已经如此优秀,让我在这个阶段就想要开始对它做一些介绍和吹捧。
很遗憾,自己读这本书还是晚了些。要是能够在最开始学习技术的时候就读到,想必能少走不少弯路。以我自己的观点来看,要掌握任何一个领域的技术,一个很重要的点就是一定要聆听大师的指导。如果你运气够好在自己身边遇到了一位大神,你可以直接向他请教。而如果没有这样的运气,那自己便需要多花费点功夫,去找大师写的文章和著作阅读,特别是那些关于review和观点的著作。因为,对于一个初学者来讲,刚进入一个领域,他有且只能看到繁复的细节,并不知道该以何种方式在脑海中把这些凌乱的碎片,系统、有条理地在脑海中组织起来。所以,阅读大师的这些综述性的著作,其目的,就是要在脑海中建立正确的看待这个领域的思维框架。
Joel关于Specification文档撰写的讨论,就是一个很好的例子。对大部分不合格的programmer来讲,写文档、写注释是一件无足轻重、讨厌至极的事情。在他们眼中,唯有代码是真正值得关心的东西,因为只有代码才可以让计算机工作啊,而一堆论述性的文档,写出来也无法被运行,那不就是浪费时间吗?!
而对另一群程序员来讲,代码恰恰是最后的、水到渠成的结果性的东西,不是你应该花费大量时间耕作的东西。对他们来讲,如果你能够写出清晰、细致的文档,代码自然就会优质卓越。如同揠苗助长这个故事的寓意,你无法通过把秧苗拔高,来加速秧苗的成长,你能做的,是更好地耕耘、施肥,尽力提供促进植物生长的环境。单纯地把精力花费在代码的细节上,就是在强制性地拔高秧苗,希望通过最直接的方式,来加速你项目的完成。而写文档,则是提前为后面复杂的代码提供良好的生长环境——清晰准确的逻辑。在这样的牢实的基础上,你的项目自然可以快速成长。
大部分做技术的人,会过分地注重勤于动手,而忘记了更重要的一步——先动脑。在他们看来,“开大会、打嘴炮、写文档”,都是一些business上的该死的流程,都是在务虚,不务实。由于已经在脑海中定下“无用”的论调,自然更是没有机会去理解其中的精髓。
“开大会、打嘴炮、写文档”,如果用讽刺的话来讲,就是“纸上谈兵”。可是,还有另一个褒义的描述——沙盘演练。对于任何一个项目来讲,前期的需求确认,是极其重要的。因为它是后续所有流程的根基。流程的更改、方向的变更,如果发生在技术开发的过程中,其损害的成本非常巨大,你不得不调整构架、重新组织甚至删除你已投入大量精力的工作。而如果这个事情发生在似乎不怎么有用的“开大会、打嘴炮、写文档”呢?那无非就是多耗费一点口水,重新写一行文字罢了。
撰写spec文档,就好比是画家最开始在画板上勾勒的辅助线。粗糙的一横、一竖,潦草的正方形框、椭圆形脑袋,不一而足。而如果你去观察刚学画的小朋友,大多有一个共同特征:几乎无法经受住描绘细节的诱惑,一开始就精细地刻画眼睛、嘴巴、肌肉的纹路。而最后的结果也是理所当然的四不像,错位、扭曲、畸形的五官与大小各异的四肢组合。通常,老师会花费大量的时间去纠正初学者这种从局部出发的坏习惯,让他们逐渐适应、掌握从整体的框架出发,再逐步深入细节的技巧。
写代码和写文档的关系,就是这样精致描绘细节和简单勾勒草图的关系。
当你所写的项目稍微多涉及几个现实的事务,其业务逻辑就不会如你现象中的那样简单。例如写一个用户登录的输入框,乍一看,似乎没什么精细复杂的地方,于是大摇大摆地动手写起代码来。行至途中,通常会发现各种小问题,前面忘记一个验证数据,后面忘记一个记录cookie,搞得自己狼狈不堪。可如果你肯多花费一点时间,将spec文档写好,把每一个流程图、状态图庙会清楚,就等于是为后面的代码撰写提前做了一次沙盘演练,能让你成竹在胸。
而另一方面,软件开发是协作性的事物,仅仅是团队工作中的一个环节。你对代码的理解,往往只是代表你自己的个人意见,难保与你合作的产品经理、老板、其他部门会有不同看法。难道要把整个项目都写完,才去征求他们的意见吗?!
这就是提前撰写spec文档的另一个好处:你可以在写代码之前,就把流程理解记录下来,让项目相关人士提前审阅,从而以最小的成本,提前修正方向性的争论和问题。
近期回顾
《叫兽的逻辑 | #Metoo》
《不会谈》
《编程语言吐槽之Java与C》
如果你喜欢我的文章或分享,请长按下面的二维码关注我的微信公众号,谢谢!
更多信息交流和观点分享,可加入知识星球:
VIP赞赏专区:
为什么需要提前撰写Spec文档的更多相关文章
- 使用 VS Code 撰写 Markdown 文档
众所周知, VS Code 是微软和社区一起开发的一款很优秀的高级代码编辑器.它不仅可以写出一手好代码,还能写出一篇好文章.利用 Markdown 就可以写出一篇排版美观的技术文章了. 而 Markd ...
- 产品需求文档(PRD)的写作方法之笔记一
1.写前准备(思维导图): http://www.woshipm.com/?p=80070 1.在写之前,请先很区分清楚什么是MRD文档(市场需求文档),BRD文档(商业需求文档),什么是PRD文档( ...
- [转]产品需求文档(PRD)的写作
产品需求对产品研发而言非常重要,写不好需求,后面的一切工作流程与活动都会受到影响.转载一篇文章,关于产品需求文档写作方面的,如下: 本文摘自(一个挺棒的医学方面专家):http://www.cnblo ...
- 产品需求文档(PRD)的写作 【转】
产品需求文档(PRD)的写作 一.文章的摘要介绍 无论我们做什么事都讲究方式方法,写产品需求文档(以下称PRD文档)也是如此,之前我通过四篇文章分享了自己写PRD文档的一些方法,而这一篇文章主要是 ...
- Laravel框架内实现api文档:markdown转为html
前后端分离的工作模式于今是非常流行了,前后端工作的对接,就离开不了API文档的辅助. 根据自己以往的工作经历,以及了解的一些资讯,API文档的建立,无非以下几种方式: 1. word文档模板 2. 第 ...
- es之文档更新过程中并发冲突问题
1:乐观锁控制 ES是分布式的,也是异步并发的,我们的复制请求是并行发送的:这就意味着请求到达目的地的顺序是不可控制的,是乱序的: 如果是乱序的方式,很有可能出现这样的一个问题,新version的文档 ...
- 文档驱动开发模式在 AIMS 中的应用与实践
摘要:程序员常会说:我最讨厌别人写的代码没有文档,我也最讨厌自己需要写文档. 有一个很老的梗: 我最讨厌别人写的代码没有文档,我也最讨厌自己需要写文档. 有这种想法的程序员应该算是一个老鸟了,对于大多 ...
- 有了Swagger2,再也不用为写Api文档头疼了
1.为什么要写Api文档 现在,前后端分离的开发模式已经非常流行,后端开发工程师只负责完成后端接口,前端页面的开发和渲染完全由前端工程师完成. 问题来了,前端工程师怎么知道后端接口的具体定义呢?答案是 ...
- 如何写Markdown格式文档
Markdown Markdown是一种轻量级标记语言,创始人为约翰·格鲁伯.它允许人们使用易读易写的纯文本格式编写文档,然后转换成有效的XHTML(或者HTML)文档.这种语言吸收了很多在电子邮件中 ...
随机推荐
- Codeforces Round #553 (Div. 2) D题
题目网址:http://codeforces.com/contest/1151/problem/D 题目大意:给出n组数对,(ai , bi),调整这n组数对的位置,最小化 ∑(ai*( i -1)+ ...
- selenium之 chromedriver与chrome版本映射表(更新至v2.46)
chromedriver版本 支持的Chrome版本 v2.46 v71-73 v2.45 v70-72 v2.44 v69-71 v2.43 v69-71 v2.42 v68-70 v2.41 v6 ...
- scrapy 爬取智联招聘
准备工作 1. scrapy startproject Jobs 2. cd Jobs 3. scrapy genspider ZhaopinSpider www.zhaopin.com 4. scr ...
- [DP][NOIP2013]花匠
花匠 问题描述: 花匠栋栋种了一排花,每株花都有自己的高度.花儿越长越大,也越来越挤.栋栋决定把这排中的一部分花移走,将剩下的留在原地,使得剩下的花能有空间长大,同时,栋栋希望剩下的花排列得比较别致. ...
- 颜色16进制转为RGB格式
<script> 2 function getRGB(str){ var arr = str.split(""); var myred = arr[1]+arr[2]; ...
- [精华][推荐]CAS SSO实现单点登录框架学习源码
1.通过下载稳定版本的方式下载cas的相关源码包,如下: 直接选择4.2.1的稳定代码即可 2.我们项目中的版本版本使用maven apereo远程库去下载 通过远程maven库下载cas-serve ...
- java之路 数据类型-常量
class Demo1{ public static void main(String[] args){ //数据类型 类名 = 初始值 int age = 10; int age1 = 20; Sy ...
- 浅谈 drop、truncate和delete的区别
(1)DELETE语句执行删除的过程是每次从表中删除一行,并且同时将该行的删除操作作为事务记录在日志中保存以便进行进行回滚操作. TRUNCATE TABLE 则一次性地从表中删除所有的数据并不把单独 ...
- chrome gps位置模拟设置
chrome gps位置模拟设置 调试公众号页面定位,Edge 虽好实现方便,介于界面实在不符合我的调试习惯 遂上度娘寻觅chrome模拟GPS方法 找了好几个帖子,发现新版本已经不再试用.不得感叹 ...
- 阿里巴巴Java编码规范插件安装使用指南
编码规范插件安装使用指南 阿里技术公众号公布的<阿里巴巴Java开发规约>,瞬间引起全民代码规范的热潮,后又发布了PDF的终极版,大家踊跃留言,期待配套的静态扫描工具开放出来. 为了让开发 ...