学步园

Joel on Software

Painless Functional Specifications - Part 4: Tips

无痛功能需求 –第四部分：技巧

by Joel Spolsky Sunday, October 15, 2000

OK, we've talkedabout  why you need aspec, what a spechas in it, andwho
shouldwrite them. In this fourth and final part of the series I'll share some ofmy advice for writing good specs.

好，我们已经讨论了 为什么你需要规范， 规范包含什么内容， 以及谁应该编写规范。 在这些列的第四部分同时也是最后一部分我将和大家分享我编写好规范的建议。

The biggestcomplaint you'll hear from teams that do write specs is that"nobody reads them." When nobody reads specs, the people who writethem tend to get a little bit cynical. It's like the old Dilbert cartoon inwhich engineers use stacks of 4-inch
thick specs to build extensions to theircubicles. At your typical big, bureaucratic company, everybody spends monthsand months writing boring specs. Once the spec is done, it goes up on theshelf, never to be taken down again, and the product is implemented
fromscratch without any regard to what the spec said, because nobody read the spec,because it was so dang mind-numbing. The very process of writingthe spec might have been a good exercise, because it forced everyone, at least,to think over the issues.
But the fact that the spec was shelved (unread andunloved) when it was completed makes people feel like it was all a bunch ofwork for naught.

你从那些确实编写规范的团队听到的最大抱怨就是“没有人会读规范”。如果没有人阅读规范，那么写规范的人就会有点儿愤世嫉俗。就像迪尔伯特漫画里描绘的那样，工程师们使用一摞摞4英寸厚的规范来扩展他们的工作隔间。在你们那些大的，官僚作风的典型公司，每个人都会花数月来编写无聊的规范。规范一写完就会被放到架子上去，再也不会被拿下来，而产品则是从头做起绝不会参照任何规范的描述，因为没有人阅读规范，因为规范是如此的让人头皮发麻（无聊，愚蠢）。编写规范的过程也许是个很好的训练，因为它让每个人至少去仔细思考这些问题，但是规范完成后就被高高搁置（没人爱也没人读）让人觉得写规范就是件徒劳无功的工作。

Also, if yourspec never gets read, you get a lot of arguments when the finished product isdelivered. Somebody (management, marketing, or a customer) says: "wait aminute! You promised me that there would be a Clam Steamer! Where's the clamsteamer?" And the
programmers say, "no, actually, if you look on thespec on chapter 3, subchapter 4, paragraph 2.3.0.1, you'll see it says quiteexplicitly 'no clam steamer.'" But that doesn't satisfy the customer, whois always right, so the grumpy programmers have to go retrofit
a clam steamerinto the thing (making them even more cynical about specs). Or a manager says,"hey, all the wording on this dialog is too verbose, and there should bean advertisement at the top of every dialog box." And the programmers say,in frustration, "but
you approved the spec whichprecisely listedthe layout and contents of every dialog box!" But of course, the managerhadn't actually read the spec, because when he tried, hisbrain started seeping out through his eye sockets, and anyway,
it wasinterfering with his Tuesday golf game.

同时，如果你的规范从来没被阅读过，当你的产品完成并交付的时候你就会遇到很多争端。有人（管理层，销售，或者顾客）就会说：“等等！你答应过我会做蛤蜊蒸笼[w1] ！蛤蜊蒸笼在哪儿？”然后程序员就会说，“不，实际上，如果你看看规范第三章第4小节，2.3.0.1段，你就会很清楚的看到写着‘没有蛤蜊蒸笼’”。不过这不会让客户满意，因客户永远是对的，所以暴躁的程序员只好去产品里改造出个蛤蜊蒸笼来（这就让规范存在的意义显得更讽刺了）。或者经理会说，“嘿，这个对话框上的文字太冗余了，而且每个对话框的顶部都应该要个广告。”然后程序员就会很沮丧的说，“但你已经批准了这个规范，规范上准确无误的描述了每个对话框的布局和内容。”但是，经理实际上当然没有去读那个规范，因为他刚要尝试,他的思绪就透过他的眼睛飘了出去，再说，这打扰了他礼拜二的高尔夫球比赛。

So. Specs aregood, but not if nobody reads them. As a spec-writer, you have to trickpeople into reading your stuff, and you should also probably make aneffort not to cause any already-too-small brains to leak out througheye-sockets.

所以规范是好的，但如果没人读就是另一码事了。作为一个规范写作家，你应该设法骗人去读你的东西，而且你最好努力不要让已经很小的思绪从眼球里溜出去。

Tricking peopleinto reading your stuff is usually just a matter of good writing. But it's notfair of me to just say "be a good writer" and leave it at that. Hereare four easy rules that you absolutely must follow to makespecs that get read.

骗人读你的东西通常就是好好写作罢了。但要是我只是说“做个好作家”然后就罢了未免有点太不公平。如果你想写出会被读的规范，下面是四点你绝对要遵从的原则。

Rule 1: BeFunny 原则一：要有幽默感

Yep, rule numberone in tricking people into reading your spec is to make the experienceenjoyable. Don't tell me you weren't born funny, I don't buy it. Everybody hasfunny ideas all the time, they just self-censor them because they think thatit's "unprofessional."
Feh. Sometimes you have to break the rules.

是的，要骗人来读你的规范的第一原则就是要让这段经历变得享受。不要告诉我你生来就不幽默，我才不信呢。每个人一直都有幽默的想法，只不过因为他们觉得那显得“很不专业”因此主动屏蔽了他们。有时候你得打破这些条条框框。

If you readthe volumesof garbage I've written on this web site, you'll notice that there area few lame attempts at being funny scattered throughout. Just four paragraphsago
I was making a grossbody-fluid[w2] 
joke and making fun of managers for playing golf. Even though I'm notreally that funny, I still try pretty hard, and even the act of flailingaround trying to be funny is in itself amusing, in a sad-clownsort of way. When you're writing a spec,
an easy place to be funny is in theexamples. Every time you need to tell a story about how a feature works,instead of saying:

如果你读到了我在这个网站上写的“垃圾的容量”，你就会发现其中也有一些很“傻”的尝试刻意幽默。就在四个段落之前，我编了个黄色笑话，并且取笑经理们玩高尔夫球。即使我没那么幽默，我还是很努力在尝试，甚至故作姿态以一种悲伤小丑方式来幽默本身就是有趣的。当你在编写规范的时候，最简单作幽默的地方就是在例子里。每当你要讲个故事来阐述某项特性是如何工作的时候，与其说：

·   The user types Ctrl+N to create a new Employee table and startsentering the names of the employees.

·   用户按下Ctrl+N来创建新员工表，并且开始录入员工姓名。

write somethinglike:

不如写点这样的东西：

·   Miss Piggy, poking at the keyboard with a eyeliner stick because herchubby little fingers are too fat to press individual keys, types Ctrl+N tocreate a new Boyfriend table and types in the single record "Kermit."

·   Piggy小姐用眼线棒敲着键盘，因为她的丰满的手指太胖了没办法按下一个键位，按下Ctrl+N来创建一个新的男友表，然后输入了一条记录“Kermit”。

If you read a lotof DaveBarry, you'll discover that one of the easiest ways to be funny is tobe specific when it's not called for. "Scrappy pugs"are
funnier than "dogs." "Miss Piggy" is funnier than"the user". Instead of saying "special interests," say"left-handed avocado farmers." Instead of saying "People whorefuse to clean up after their dogs should be punished," say that theyshould be "sent to prisons
so lonely that the inmates have to pay spidersfor sex."

如果你读过很多Dave Barry的著作，你就会发现幽默最简单的方式就是在不需要的时候特定点。“旺财”比“狗”幽默。“Piggy小姐”比“用户”幽默。与其说“特殊爱好”，不如说“左撇子梨树农夫”。 与其说“在他们的狗做了应该被惩罚的事之后人们不愿意打扫”不如说“他们应该被关进那种监狱，在那里，囚犯们太寂寞以致于要付钱跟蜘蛛乱搞。”。

Oh, and, by theway, if you think that it's unprofessional to be funny, then I'm sorry, but youjust don't have a sense of humor. (Don't deny it. People without senses ofhumors always deny it. You can't fool me.) And if you work in a company wherepeople will
respect you less because your specs are breezy, funny, andenjoyable to read, then gofind anothercompany to work for, because life is just too damn shorttospend your daylight hours in such a stern
and miserable place.

。哦，另外，顺便说一下，如果你觉得幽默是那么不专业的话，那么我很抱歉，你就是没有幽默感（别否认，没有幽默感的人总是抵赖，你骗不了我。）另外，如果你工作的公司因为你写的规范轻松活泼，幽默，令人读来十分愉悦而不尊重你的话，另外找个公司工作吧，因为把你的宝贵白天时间花费在这么个严厉而可悲的地方简直都能让人折寿。

Rule 2: Writinga spec is like writing code for a brain to execute

原则二：写规范就像是写大脑执行的代码

Here's why Ithink that programmers have trouble writing good specs.

这就是为什么我认为程序员无法写出好的规范的原因。

When youwrite code, your primary audience is the compiler.Yeah, I know, people have to read code, too, but it's generally very hard forthem. For most
programmers it's hard enough to get the code into a statewhere the compiler reads it and correctly interprets it; worrying about makinghuman-readable code is a luxury. Whether you write:

当你写代码的时候，你的主要对象是编译器。是的，我知道，人也得会阅读代码，但总体来说对他们很难。对大多数程序员来说让编译器正确理解他们的代码已经足够困难了；操心要写出人类可读的代码实在太奢侈了。当你写出：

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 deliberatelyobfuscated 代码被故意混淆过了 */ }

or 或是

printf("thereare 10 employees\n");

you getthe same output. Which is why, if you think about it, you tend to getprogrammers who write things like:

你得到的输出都是一样的。如果你仔细想想，这也就是为什么，你更倾向于要雇佣能写出这样的东西的程序员:

Assume a functionAddressOf(x) which is defined as the mapping from a user x,to the RFC-822 compliant email address of that user, an ANSI string. Let usassume user A and user B, where A wants to send an email to user B. So user Ainitiates
a new message using any (but not all) of the techniques definedelsewhere, and types AddressOf(B) in the To: editbox.

假定一个函数 AddressOf(x) 定义了从一个用户x到该用户的符合RFC-822标准规定的email地址映射ANSI字符串，假定用户A和用户B，用户A想要给用户B发送电子邮件。所以用户A采用其他任意定义的技术（但不是所有）起草了一个新的信息，并在“发送到”编辑框内输入了AddressOf（B）。

This could alsohave been speced as:

这段规范也可以这样描述：

Miss Piggy wantsto go to lunch, so she starts a new email and types Kermit's address in the"To:" box. 

肥肥小姐想要去吃午饭，所以她就起草了封新邮件并且把Kermit的地址输入到了 “发送到”地址框内。
Technical note: the address must be a standard Internet address(RFC-822 compliant.)

技术提示：地址必须是标准因特网地址（符合RFC-822规范）。

They both"mean" the same thing, theoretically, except that thefirst example is impossible to understand unless you carefully decode it, andthe second example is easy to understand. Programmers often try to write specswhich look like dense academic
papers. They think that a "correct"spec needs to be "technically" correct and then they are off thehook.

理论上来说，它们说的都是同一件事情，但如果你不细细体会，你不可能理解第一个例子的内容。程序员总是倾向于写出像厚厚的学术文章那样的规范。他们认为一个“正确的”规范必须“技术上”是正确的，然后他们就摆脱这个问题了。

The mistake isthat when you write a spec, in addition to being correct, it has to be understandable,which, in programming terms, means that it needs to be written so that thehuman brain can "compile" it. One of the big differences betweencomputers
and human brains is that computers are willing to sit there patientlywhile you define the terms that you want to use later. But humans won'tunderstand what you're talking about unless you motivate it first. Humans don'twant to have to decode something,
they just want to read it inorder and understand it. For humans, you have to provide the big pictureand then fill in the details. With computer programs, youstart at the top and work your way to the bottom, with full details throughout.A computer
doesn't care if your variable names are meaningful. A human brainunderstands things much better if you can paint a vivid picture in their mindby telling a story, even if it's just a fragment of a story, because our brainshave evolved to understand stories.

错误在于当你编写规范的时候，除了要正确，它必须是能被理解的，用编程术语来讲就是说，它应该写成人脑能正确编译的那样。人脑和电脑最大的差别之一就在于：当你在定义以后要用的术语的时候，电脑能安静的在旁耐心等待。而人脑如果你不激励它，它根本就不能理解你在讲什么。人类不会想要去“解码”什么东西，它们只想顺序阅读然后能理解它。对人而言，你必须先提供宏观的描述然后在描绘细节。用电脑程序，你能够从最顶层开始一直工作到最底层的全部细节。电脑不管你的变量名是否有意义。而人脑如果你能够通过讲故事，哪怕是一小片段，在它们的脑海中描绘一幅栩栩如生的图画那么人脑理解起来就好多了。因为我们的大脑参与进来，来理解故事。

If you show achess board, in the middle of a real game of chess, to an experienced chessplayer for even a second or two, they will instantly be able to memorize theposition of every piece. But if you move around a couple of pieces innonsensical ways that
couldn't happen in normal play (for example, put somepawns on the first row, or put both black bishops on black squares), it becomesmuch, much harder for them to memorize the board. This is different from theway computers think. A computer program that could
memorize a chess board couldmemorize both possible and impossible layouts with equal ease. The way thehuman brain works is not random access; pathways tend to bestrengthened in our brains and some things are just easier to understand thanother things
because they are more common.

如果你向一个经验丰富的棋手展示一幅进行中的真实棋盘，哪怕只有一两秒，他们马上能够记起每个棋子的位置。但如果你用正常比赛中不会出现的非理性方式走两步棋（例如，在第一排布两个卒，或者把两个相都放在黑格子中[w3] ），要让他们再记住棋盘就困难多了。这跟计算机的记忆方式是不一样的。计算机程序要记忆可能和不可能的布局是一样容易的。而人脑的工作方式并不是随机访问；过程更容易在我们大脑中得到加强，而有些东西就是比其他东西更容易记忆因为它们更加平常。

So, when you'rewriting a spec, try to imagine the person you are addressing it to, and try toimagine what you're asking them to understand at every step. Sentence bysentence, ask yourself if the person reading this sentence will understandit at
a deep level, in the context of what you've already told them.If some members of your target audience don't know what RFC-822 is, you eitherhave to define it, or, at the very least, bury the mention of RFC-822 in atechnical note, so that the executive-types
who read the spec won't give up andstop reading the first time they see a lot of technical jargon. 

所以，当你在编写规范的时候，尝试想象你正在给其陈述的对象，尝试去想象每一步你要让他们理解些什么。一句一句地，问问你自己，在你已经阐述的上下文中，如果别人读到这个句子能否深层次的理解它。如果你的受众群体的一些人并不知道什么是RFC-822，你要么得定义它，或者至少在技术提示里提一下RFC-822，这样那些执行董事们在阅读你的规范的时候不会一看到技术术语就放弃然后停止阅读。

Rule 3: Writeas simply as possible

原则三：写得越简单越好

Don't usestilted, formal language because you think it's unprofessional to write insimple sentences. Use the simplest language you can. 

不要因为你觉得用简单的句子显得不专业就用做作的正式语言。使用你能使用的最简单语言。

People use wordslike "utilize" because they think that "use" looksunprofessional. (There's that word "unprofessional" again. Any timesomebody tells you that you shouldn't do something because it's"unprofessional," you know that they've run out of real arguments.)In
fact I think that many people think that clear writing means that somethingis wrong.

人们会因为“采用”显得不专业而使用诸如“选取”这样的词语。（又出现了“不专业”这个词。每当有人告诉你因为那不专业而不要做某件事情的时候，你就应该意识到他们其实没什么真实的论据。）实际上我认为很多人觉得清楚的写作意味着什么东西出错了。

Nothing improvesa spec more than lots and lots of screenshots. A picture can be worth athousand words. Anyone who writes specs for Windows software should invest in acopy of Visual Basic, and learn to use it at least well enoughto create mockups
of the screens. (For the Mac, use REAL Basic; for Web pages,use Front Page or Dreamweaver). Then capture these screenshots (Ctrl+PrtSc) andpaste them into your spec.

没有什么能够比大批大批的截图更能改进规范了。 一张图胜过一千句话。任何为Windows软件写规范的人都应该投资买一份VisualBasic，然后至少要学会用它来创建屏幕模型。（Mac用户请使用RealBasic；网页开发请使用FrontPage或Dreamwaver）。然后捕捉截屏（Ctrl+PrtSc）并把它们粘贴进你的规范。

Rule 4: Reviewand reread several times

第四原则：评审并重读若干次

Um, well, I wasoriginally planning to have a lengthy exegesis of this rule here, but this ruleis just too simple and obvious. Review and reread your spec several times, OK?When you find a sentence that isn't super easy to understand,rewrite it.

嗯，很好我本打算在这里对这条规则写上冗长的解释，但这条原则是在太简单太明显了。多评审和阅读几次，好么？当你觉得有个句子读起来不是那么简单易懂的时候，重写吧。

I've saved somuch time by not explaining Rule 4 that I'm going to add another rule.

不解释第四条原则帮我节省了这么多的时间，我决定在加一个原则。

Rule 5:Templates considered harmful

原则五：模板是有害的

Avoid thetemptation to make a standard template for specs. At first you might just thinkthat it's important that "every spec look the same." Hint: it's not.What difference does it make? Does every book on your bookshelf at home lookexactly the same? Would
you want them to?

避免为规范制作标准模板的冲动。一开始你可能觉得“所有的模板都有一种一致性”看起来很重要。提示：不是这样的。这样有什么好处呢？你家里书架上的书看起来都一样么？你希望它们一样么？

Worse, if youhave templates, what tends to happen is that you add a bunch of sections to thetemplate for things that you think are important for every feature. Example:Big Bill decrees that from here on forward, every Microsquish product shallhave an Internet
component. So the spec template now has a section that says"Internet Component." Whenever somebody writes a spec, no matter howtrivial, they have to fill in that section that says "InternetComponent", even if they're just creating the spec for the MicrosquishKeyboard.
(And you wondered why those useless Internet shopping buttons startedcropping up like mushrooms on keyboards).

更糟的是，如果你有模板，通常会发生的事情是：你会为你觉得对每个特性都很重要的地方都添加一个部分。例如：大比尔法令规定，从今往后，所有Microsquish产品都必须有因特网部件。因此现在所有的规范模板都有一个叫做“因特网部件”的部分。不管谁写规范，不管多么简单，他们都必须去填写那个叫做“因特网部件”的部分，哪怕他们只是要为Microsquish键盘编写一个规范。（你很诧异为什么那些因特网购物按钮开始像蘑菇一样从键盘上冒出来）。

As these sectionsaccumulate, the template gets pretty large. (Here is an example of a very, very badtemplate for specifications. Who needs a bibliography in aspec, for
heaven's sake? Or a glossary?) The trouble with such a large templateis that it scares people away from writing specs because it looks like such adaunting task.

随着这些部分的积累，模板就会越来越大。（这儿有个非常非常糟的规范模板。天呐，谁会想要在规范里写个自传？还有一个词汇表？）这么大的规范模板的问题在于：它会把编写规范的人吓跑因为人们会觉得这是多么恐怖的一件事情。

A spec is adocument that you want people to read. In that way, it is no different than anessay in The New Yorker or a college paper. Have you everheard of a professor passing out templates for students to write their collegepapers? Have you ever
read two good essays that could be fit into a template?Just drop the idea.

规范是你希望人们去读的文档。这样它就跟《纽约客》上的散文或是校报上的散文没有区别了。你听说过教授分发模板让学生们在校报上写文章的么？你读到过俩篇好文章你塞进一个模板的么？放弃这个想法吧。