无痛功能规格- 第四篇：提示

作者：周思博(Joel Spolsky)
译：Paul May 梅普华
编辑：Jeff Wang 王家麒
October 15, 2000
A part of Joel on Software, http://www.joelonsoftware.com

好吧，我们已经讨论过[为什么要规格](/wiki/The_Joel_on_Software_Translation_Project:%E7%84%A1%E7%97%9B%E5%8A%9F%E8%83%BD%E8%A6%8F%E6 %A0%BC(%E4%B8%80) “The Joel on Software Translation Project:无痛功能规格(一)")，[规格里有什么](/wiki/The_Joel_on_Software_Translation_Project:%E7%84%A1%E7%97%9B%E5%8A%9F%E8%83%BD% E8%A6%8F%E6%A0%BC(%E4%BA%8C) “The Joel on Software Translation Project:无痛功能规格(二)")，以及[谁该写规格](/wiki/The_Joel_on_Software_Translation_Project:%E7%84%A1%E7%97%9B%E5%8A%9F%E8%83%BD %E8%A6%8F%E6%A0%BC(%E4%B8%89) “The Joel on Software Translation Project:无痛功能规格(三)")。在这系列的第四篇及最后一篇里，我要和大家分享一份撰写良好规格的建议。

在_真正_ 有写规格的团队中最大的抱怨就是「没有人在读」。如果没有人在读，写规格的人通常会变得有点愤世嫉俗。就像以前呆伯特漫画里，工程师用一大叠4吋厚的规格书堆起来充当隔间。在典型官僚作风的大公司里，每个人都花好几个月写无聊的规格。等规格写好就放上书架永远不再拿下来，然后重头开始制作产品，完全不管规格里怎么写。这是因为没人读规格同时也是因为规格写得 无聊透顶 。写规格的过程应该是个很好的练习，因为它至少能强迫每个人仔细思考问题。不过规格完成后就被束之高阁(没人看也没人爱)，会让大家觉得这只是件毫无价值的工作。

另外如果没有人读你的规格，等产品完成推出就会出现很多争议。某人(管理阶层，行销人员或是客户)会说：「等一下！你答应过会有蛤蜊蒸锅的！蛤蜊蒸锅在哪里？」然后程式员会说：「不，事实上如果你看看规格第3章第4节的2.3.0.1，就会看到上面明确写着’没有蛤蜊蒸锅。」不过永远是对的客户可没这么好打发，所以不爽的程式员只好在产品里加一个蛤蜊蒸锅(结果让他们更不相信规格)。另外也可能会有个经理说：「嘿，这个对话框里的文句都太累赘了，而且每个对话框上方应该都有广告才对。」然后程式员会垂头丧气地说：「可是你 批准了规格 而且里面_明确的_ 列出每个对话框的配置和内容！」不过经理当然不会真正去_读_ 规格，因为当他想看的时候就开始心不在焉，而更重要的是这和他周二的高尔夫球比赛有冲突。

所以说虽然规格是很好的，不过如果没人读就不好了。身为撰写规格的人，你必须_骗大家_ 来读你的作品，另外也可能要努力不要让大家过份依赖规格而失去原本已经很差的思考力。

要骗大家来读你的作品，通常只需改善写作即可。不过光说句「要当个好作家」就撤手不管实在不太公道。下面列出想让别人读规格时_绝对要_ 遵守的四个简易规则。

规则1：要有趣

是的，要骗大家来读规格的第一个规则就是让读规格变得很有趣。别告诉我你生来就没有幽默感。我才不信呢。每个人随时都会有好玩的点子，只不过因为觉得会「不专业」所以自我约束。不过有时候你得要打破规则。

如果你读过我在这个网站写的一堆垃圾，你会注意里面到处都有想让内容更有趣的拙劣企图。另外往前数第四段我才刚写了个低级玩笑取笑经理在打高尔夫球。虽然我实际上没那么幽默，我还是很努力在尝试。另外虽说胡扯乱扯试图表现有趣本身就很滑稽，却是属于悲哀的那一型。在写规格时范例是个表达趣味的好地方。当你需要说个故事解释某个功能时，千万不要这样说：

1. 使用者按Ctrl+N建立一个新的雇员表格，并且开始输入雇员姓名。

你应该要这样写：

1. 猪小姐因为手指太肥按不到单一的键，所以拿着一根眼线笔戳键盘按出Ctrl+N建出一个新的男友表格。然后输入单一笔资料"Kermit"。

如果你读过很多Dave Barry的文章，会发现有个很容易的方法可以逗趣，就是在不需要的地方 详述细节 。「爱吵闹的哈巴狗」就比「狗」有趣。而「猪小姐」也比「使用者」有趣。用「左撇子酪梨农夫」要比「特殊嗜好」好。不要用「不替狗清大便的人应该受罚」，应该说「把他们关在单人囚房，让他们寂寞到想付钱跟蜘蛛上床。」

附带一提，如果你认为逗趣不够专业，那我也没办法，只能说你缺乏幽默感。(不要否认。没有幽默感的人总是不肯承认。你是骗不了我的。)另外如果同事会因为你写的规格轻松有趣很好读而轻视你的话，就去找别的工作吧，因为生命实在 太短暂 ，不应该把你的白天浪费在这种苛刻悲惨的地方。

规则2：写规格就像在写用脑执行的程式

这就是我会认为程式员写不出好规格的原因。

当你在写_程式_ 时，主要对象是_编译器_ 。没错，我知道人也会读程式，不过通常会[读得很辛苦](/wiki/The_Joel_on_Software_Translation_Project:%E4%BD%A0%E7%B5%95%E5%B0%8D%E4%B8%8D% E6%87%89%E8%A9%B2%E5%81%9A%E7%9A%84%E4%BA%8B “The Joel on Software Translation Project:你绝对不应该做的事”)。对大部份程式员来说，光是要让程式能正常编译就够辛苦了；要把程式写得容易阅读简直是遥不可及。你可以写：

void print_count( FILE* a，char * b，int c ){
fprintf(a，“there are %d %s\n”，c，b);}

main(){ int n；n =
10；print_count(stdout，“employees”，n) /* code
deliberately obfuscated */ }

或是

printf(“there are 10 employees\n”);

输出是完全一样的 。如果你仔细想想，这就是原因所在，程式员通常都会写出如下的东西：

假设有个函数AddressOf( x )，作用是由使用者_x_ 转出该使用者的RFC-822格式电子邮件地址，并以ANSI字串输出。让我们假设有使用者A和使用者B，A想送电子邮件给使用者B。所以使用者A用其他任意(不是全部)技术建立新讯息，然后在「传送至：」编辑框内键入AddressOf(B)。

这也可以写成以下的规格：

猪小姐想去吃午饭了，所以打了一封电子邮件并在「传送至：」框内键入Kermit的地址。

技术注解： 地址必须是标准的Internet地址(RFC-822格式)

理论上 这两种写法的「意思」完全一样，不过除非你很小心的解译，否则是不可能看懂第一种写法的。程式员常会尝试把规格写得像艰涩的学术论文。他们认为一份「正确」的规格必须在「技术」上完全正确，结果完全搅不清楚状况。

问题在于规格不光是正确就好，同时还必须是可理解的，以程式设计的术语来说，就是要把规格写得让人脑能够「编译」。电脑和人脑间最大的差别之一，就是当你定义稍后要用的辞语时电脑会耐心等候。可是对人来说一定要先有动机才会了解你在讲什么。人们不会想被迫解译某些东西，他们只想循序阅读就能理解。对人来说，你必须先提供整体概念_然后才_ 填补细节。而电脑程式则是从头到尾顺序下来全部都是细节。电脑不在意变数名称是否有意义。而对人脑而言，如果能先讲个故事(即使只是片断也可以)描绘出鲜明的印象，就能够理解得更清楚。因为我们的脑袋已经演进到能理解故事了。

如果你拿出真实西洋棋赛进行中途的棋局，经验够的老手只要一两秒就能立刻记住每个棋子的位置。不过如果以正常下棋不会走的方法(比如把卒放在第一列或把两只黑主教都放在黑格上)移动几颗棋子，棋手就很难记下棋局。这和电脑思考的方式不同。对能记忆棋局的电脑程式来说，可能及不可能的棋局记起来都一样。人脑的运作方式并不是随机存取的；我们脑中的某些路径会被持续加强，所以某些常见的事物就会比其他东西更易理解。

所以当你在写规格时得试着想像你的对象是谁，并且想像规格各个部份是要他们了解什么东西。逐句逐句地问自己，就前面已经提供的内容而言，读到这句话的人能深入理解其涵义吗？如果对象中有些人不知道RFC-822是什么，你必须把定义写出来，或者至少在技术注解中简述RFC-822，这样非技术人员才不会一开始就看到一堆专业术语，结果投降永不再看。

规则3：写得 愈简单愈好

千万不要觉得简单句子不够专业，就使用夸大的正式语句。写得愈简单愈好。

人们会认为"use"不够专业所以改用"utilize"之类的单字。(「不够专业」这句话又出现了。不管任何时候，只要有人说你不应该如何如何，因为那样「不够专业」，你就知道这些人已经没有真正的理由了。)事实上我认为很多人会觉得写得清楚明了就表示里面大有文章。

把要讲的东西拆成短句。如果你没办法把某个句子写得很清楚，就把它拆成二或三个较短的句子。避免整面的文字墙：也就是说整页都只有文字。大家遇到这种情况就会吓到根本不敢看。你什么时候看过有热门杂志或报纸里整页都是文字的？杂志会从文章里摘录引言，然后用超大字体印在页面正中央，就是为了避免有整页都是文字的印象。有编号或标上符号的列表，图片，图表，表格以及大量空白，都可以让东西「看起来」更轻松。

「杂志会从文章里摘录引言，然后用超大字体印在页面正中央，就是为了避免有整页都是文字的印象。」

没有东西比撷取大量的画面更能增进规格了。正所谓一图胜千言。撰写视窗软体规格的人都应该买一套Visual Basic，然后学到_至少_ 能建立模拟画面。(在麦金塔上就用REAL Basic；写网页就用Front Page或Dreamweaver)。然后撷取这些画面(按Ctrl+PrtSc)再贴进规格内。

规则4：审阅多次并重读几遍

嗯，好吧，本来我打算花大量篇幅来阐述这项规则，不过这一项实在是太简单明显了。把你的规格审阅多次并重读几遍，知道了吗？当你发现某个句子不是_非常_ 容易理解，就把整句重写一次。

不去解释规则4省了我很多时间，所以我要额外增加一项规则。

规 则5：使用样板是不好的

要避免制作标准规格样板的诱惑。最先你可能只是认为，让「每份规格看起来都一样」是很重要的。我的建议是这并不重要。这会有什么差别吗？你家里书架上的每本书都长得一模一样吗？你希望他们一样吗？

更糟的是如果有了样板，很容易就会针对各个自认重要的功能在样板上加上一大堆章节。举例来说，大比尔下令从今以后，所有Microsquish产品都一定要有个Internet元件。所以现在起规格样板里就有一节「Internet元件」。不管是谁在写也不管内容有多无聊，每个人都得在「Internet元件」那一节填入内容，即使他们只是在写Microsquish键盘的规格。(不然你以为为啥有那么多无用的Internet购物键像雨后春笋般从键盘上冒出来。)

等这样的章节一多，整份样板就会变得大。(这里有份非常非常糟糕的规格样板范例。我的天啊，谁会需要在规格里放 参考书目 或一份小辞典呢？)这种巨型样板的问题就是让写规格写是很可怕的工作，把大家吓得不敢去写规格。

规格就是一份你希望大家去读的文件。就这种观点来看，规格和_纽约客_ 或学校论文没啥不同。你曾听说过有哪个教授会拿样板给学生去写论文吗？你曾读过哪两篇好文章能套进一份样板吗？把这个点子忘了吧