[翻譯JoelOnSoftware]無痛功能需求–第四部分：技巧/Painless

Joel on Software Painless Functional Specifications - Part 4: Tips 無痛功能需求 – 第四部分：技巧 by Joel Spolsky Sunday, October 15, 2000 OK, we've talkedaboutwhy you need aspec,what a spechas in it, andwho shouldwrite them. In this fourt

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.

好，我們已經(jīng)討論了 為什么你需要規(guī)范， 規(guī)范包含什么內(nèi)容， 以及誰應(yīng)該編寫規(guī)范。 在這些列的第四部分同時也是最后一部分我將和大家分享我編寫好規(guī)范的建議。

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.

你從那些確實編寫規(guī)范的團隊聽到的最大抱怨就是“沒有人會讀規(guī)范”。如果沒有人閱讀規(guī)范，那么寫規(guī)范的人就會有點兒憤世嫉俗。就像迪爾伯特漫畫里描繪的那樣，工程師們使用一摞摞4英寸厚的規(guī)范來擴展他們的工作隔間。在你們那些大的，官僚作風(fēng)的典型公司，每個人都會花數(shù)月來編寫無聊的規(guī)范。規(guī)范一寫完就會被放到架子上去，再也不會被拿下來，而產(chǎn)品則是從頭做起絕不會參照任何規(guī)范的描述，因為沒有人閱讀規(guī)范，因為規(guī)范是如此的讓人頭皮發(fā)麻（無聊，愚蠢）。編寫規(guī)范的過程也許是個很好的訓(xùn)練，因為它讓每個人至少去仔細(xì)思考這些問題，但是規(guī)范完成后就被高高擱置（沒人愛也沒人讀）讓人覺得寫規(guī)范就是件徒勞無功的工作。

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.

同時，如果你的規(guī)范從來沒被閱讀過，當(dāng)你的產(chǎn)品完成并交付的時候你就會遇到很多爭端。有人（管理層，銷售，或者顧客）就會說：“等等！你答應(yīng)過我會做蛤蜊蒸笼[w1] ！蛤蜊蒸笼在哪兒？”然后程序員就會說，“不，實際上，如果你看看規(guī)范第三章第4小節(jié)，2.3.0.1段，你就會很清楚的看到寫著‘沒有蛤蜊蒸笼’”。不過這不會讓客戶滿意，因客戶永遠(yuǎn)是對的，所以暴躁的程序員只好去產(chǎn)品里改造出個蛤蜊蒸笼來（這就讓規(guī)范存在的意義顯得更諷刺了）?；蛘呓?jīng)理會說，“嘿，這個對話框上的文字太冗余了，而且每個對話框的頂部都應(yīng)該要個廣告。”然后程序員就會很沮喪的說，“但你已經(jīng)批準(zhǔn)了這個規(guī)范，規(guī)范上準(zhǔn)確無誤的描述了每個對話框的布局和內(nèi)容?！钡牵?jīng)理實際上當(dāng)然沒有去讀那個規(guī)范，因為他剛要嘗試,他的思緒就透過他的眼睛飄了出去，再說，這打擾了他礼拜二的高爾夫球比賽。

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.

所以規(guī)范是好的，但如果沒人讀就是另一碼事了。作為一個規(guī)范寫作家，你應(yīng)該設(shè)法騙人去讀你的東西，而且你最好努力不要讓已經(jīng)很小的思緒從眼球里溜出去。

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.

騙人讀你的東西通常就是好好寫作罷了。但要是我只是說“做個好作家”然后就罷了未免有點太不公平。如果你想寫出會被讀的規(guī)范，下面是四點你絕對要遵從的原則。

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.

是的，要騙人來讀你的規(guī)范的第一原則就是要讓這段經(jīng)歷變得享受。不要告訴我你生來就不幽默，我才不信呢。每個人一直都有幽默的想法，只不過因為他們覺得那顯得“很不專業(yè)”因此主動屏蔽了他們。有時候你得打破這些條條框框。

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:

如果你讀到了我在這個網(wǎng)站上寫的“垃圾的容量”，你就會發(fā)現(xiàn)其中也有一些很“傻”的嘗試刻意幽默。就在四個段落之前，我編了個黃色笑話，并且取笑經(jīng)理們玩高爾夫球。即使我沒那么幽默，我還是很努力在嘗試，甚至故作姿態(tài)以一種悲傷小丑方式來幽默本身就是有趣的。當(dāng)你在編寫規(guī)范的時候，最簡單作幽默的地方就是在例子里。每當(dāng)你要講個故事來闡述某項特性是如何工作的時候，與其說：

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

· 用戶按下Ctrl+N來創(chuàng)建新員工表，并且開始錄入員工姓名。

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來創(chuàng)建一個新的男友表，然后輸入了一條記錄“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的著作，你就會發(fā)現(xiàn)幽默最簡單的方式就是在不需要的時候特定點。“旺財”比“狗”幽默?！癙iggy小姐”比“用戶”幽默。與其說“特殊愛好”，不如說“左撇子梨樹農(nóng)夫”。 與其說“在他們的狗做了應(yīng)該被懲罰的事之后人們不愿意打掃”不如說“他們應(yīng)該被關(guān)進那種監(jiān)獄，在那里，囚犯們太寂寞以致于要付錢跟蜘蛛亂搞?！?。

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.

。哦，另外，順便說一下，如果你覺得幽默是那么不專業(yè)的話，那么我很抱歉，你就是沒有幽默感（別否認(rèn)，沒有幽默感的人總是抵賴，你騙不了我。）另外，如果你工作的公司因為你寫的規(guī)范輕松活潑，幽默，令人讀來十分愉悅而不尊重你的話，另外找個公司工作吧，因為把你的寶貴白天時間花費在這么個嚴(yán)厲而可悲的地方簡直都能讓人折壽。

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

原則二：寫規(guī)范就像是寫大腦執(zhí)行的代碼

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

這就是為什么我認(rèn)為程序員無法寫出好的規(guī)范的原因。

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:

當(dāng)你寫代碼的時候，你的主要對象是編譯器。是的，我知道，人也得會閱讀代碼，但總體來說對他們很難。對大多數(shù)程序員來說讓編譯器正確理解他們的代碼已經(jīng)足夠困難了；操心要寫出人類可讀的代碼實在太奢侈了。當(dāng)你寫出：

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:

你得到的輸出都是一樣的。如果你仔細(xì)想想，這也就是為什么，你更傾向于要雇傭能寫出這樣的東西的程序員:

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.

假定一個函數(shù) AddressOf(x) 定義了從一個用戶x到該用戶的符合RFC-822標(biāo)準(zhǔn)規(guī)定的email地址映射ANSI字符串，假定用戶A和用戶B，用戶A想要給用戶B發(fā)送電子郵件。所以用戶A采用其他任意定義的技術(shù)（但不是所有）起草了一個新的信息，并在“發(fā)送到”編輯框內(nèi)輸入了AddressOf（B）。

This could alsohave been speced as:

這段規(guī)范也可以這樣描述：

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

肥肥小姐想要去吃午飯，所以她就起草了封新郵件并且把Kermit的地址輸入到了 “發(fā)送到”地址框內(nèi)。
Technical note: the address must be a standard Internet address(RFC-822 compliant.)

技術(shù)提示：地址必須是標(biāo)準(zhǔn)因特網(wǎng)地址（符合RFC-822規(guī)范）。

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.

理論上來說，它們說的都是同一件事情，但如果你不細(xì)細(xì)體會，你不可能理解第一個例子的內(nèi)容。程序員總是傾向于寫出像厚厚的學(xué)術(shù)文章那樣的規(guī)范。他們認(rèn)為一個“正確的”規(guī)范必須“技術(shù)上”是正確的，然后他們就擺脫這個問題了。

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.

錯誤在于當(dāng)你編寫規(guī)范的時候，除了要正確，它必須是能被理解的，用編程術(shù)語來講就是說，它應(yīng)該寫成人腦能正確編譯的那樣。人腦和電腦最大的差別之一就在于：當(dāng)你在定義以后要用的術(shù)語的時候，電腦能安靜的在旁耐心等待。而人腦如果你不激勵它，它根本就不能理解你在講什么。人類不會想要去“解碼”什么東西，它們只想順序閱讀然后能理解它。對人而言，你必須先提供宏觀的描述然后在描繪細(xì)節(jié)。用電腦程序，你能夠從最頂層開始一直工作到最底層的全部細(xì)節(jié)。電腦不管你的變量名是否有意義。而人腦如果你能夠通過講故事，哪怕是一小片段，在它們的腦海中描繪一幅栩栩如生的圖畫那么人腦理解起來就好多了。因為我們的大腦參與進來，來理解故事。

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.

如果你向一個經(jīng)驗豐富的棋手展示一幅進行中的真實棋盤，哪怕只有一兩秒，他們馬上能夠記起每個棋子的位置。但如果你用正常比賽中不會出現(xiàn)的非理性方式走兩步棋（例如，在第一排布兩個卒，或者把兩個相都放在黑格子中[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.

所以，當(dāng)你在編寫規(guī)范的時候，嘗試想象你正在給其陳述的對象，嘗試去想象每一步你要讓他們理解些什么。一句一句地，問問你自己，在你已經(jīng)闡述的上下文中，如果別人讀到這個句子能否深層次的理解它。如果你的受眾群體的一些人并不知道什么是RFC-822，你要么得定義它，或者至少在技術(shù)提示里提一下RFC-822，這樣那些執(zhí)行董事們在閱讀你的規(guī)范的時候不會一看到技術(shù)術(shù)語就放棄然后停止閱讀。

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.

不要因為你覺得用簡單的句子顯得不專業(yè)就用做作的正式語言。使用你能使用的最簡單語言。

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.

人們會因為“采用”顯得不專業(yè)而使用諸如“選取”這樣的詞語。（又出現(xiàn)了“不專業(yè)”這個詞。每當(dāng)有人告訴你因為那不專業(yè)而不要做某件事情的時候，你就應(yīng)該意識到他們其實沒什么真實的論據(jù)。）實際上我認(rèn)為很多人覺得清楚的寫作意味著什么東西出錯了。

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.

沒有什么能夠比大批大批的截圖更能改進規(guī)范了。 一張圖勝過一千句話。任何為Windows軟件寫規(guī)范的人都應(yīng)該投資買一份VisualBasic，然后至少要學(xué)會用它來創(chuàng)建屏幕模型。（Mac用戶請使用RealBasic；網(wǎng)頁開發(fā)請使用FrontPage或Dreamwaver）。然后捕捉截屏（Ctrl+PrtSc）并把它們粘貼進你的規(guī)范。

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.

嗯，很好我本打算在這里對這條規(guī)則寫上冗長的解釋，但這條原則是在太簡單太明顯了。多評審和閱讀幾次，好么？當(dāng)你覺得有個句子讀起來不是那么簡單易懂的時候，重寫吧。

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

不解釋第四條原則幫我節(jié)省了這么多的時間，我決定在加一個原則。

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?

避免為規(guī)范制作標(biāo)準(zhǔn)模板的沖動。一開始你可能覺得“所有的模板都有一種一致性”看起來很重要。提示：不是這樣的。這樣有什么好處呢？你家里書架上的書看起來都一樣么？你希望它們一樣么？

Worse, if youhave templates, what tends to happen is that you add a bunch of divs 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 div that says"Internet Component." Whenever somebody writes a spec, no matter howtrivial, they have to fill in that div 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).

更糟的是，如果你有模板，通常會發(fā)生的事情是：你會為你覺得對每個特性都很重要的地方都添加一個部分。例如：大比爾法令規(guī)定，從今往后，所有Microsquish產(chǎn)品都必須有因特網(wǎng)部件。因此現(xiàn)在所有的規(guī)范模板都有一個叫做“因特網(wǎng)部件”的部分。不管誰寫規(guī)范，不管多么簡單，他們都必須去填寫那個叫做“因特網(wǎng)部件”的部分，哪怕他們只是要為Microsquish鍵盤編寫一個規(guī)范。（你很詫異為什么那些因特網(wǎng)購物按鈕開始像蘑菇一樣從鍵盤上冒出來）。

As these divsaccumulate, 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.

隨著這些部分的積累，模板就會越來越大。（這兒有個非常非常糟的規(guī)范模板。天吶，誰會想要在規(guī)范里寫個自傳？還有一個詞匯表？）這么大的規(guī)范模板的問題在于：它會把編寫規(guī)范的人嚇跑因為人們會覺得這是多么恐怖的一件事情。

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.

規(guī)范是你希望人們?nèi)プx的文檔。這樣它就跟《紐約客》上的散文或是校報上的散文沒有區(qū)別了。你聽說過教授分發(fā)模板讓學(xué)生們在校報上寫文章的么？你讀到過倆篇好文章你塞進一個模板的么？放棄這個想法吧。

[w1]形容fancy的東西

[w2]關(guān)于身體的黃色笑話

[w3]國際象棋，兩個相分別位于一黑一白格子中，不會出現(xiàn)兩個相都在黑格子中，一般不會出現(xiàn)一些卒位于第一行的情況

聲明：本網(wǎng)頁內(nèi)容旨在傳播知識，若有侵權(quán)等問題請及時與本網(wǎng)聯(lián)系，我們將在第一時間刪除處理。TEL:177 7030 7066 E-MAIL:11247931@qq.com