Překlad článku Painless Functional Speci­ca­tions – Part 4: Tips, jednoho ze série článků o psaní speci­fi­kace, který napsal Joel Spolsky (mimo jiné spolu­autor stackoverflow.com) již v roce 2000 a až na pár technic­kých nástrojů jako kdyby ho psal dneska. S jeho laskavým svolením jsem text přeložil do češtiny (překlad uvolňuji pod licencí Creative Commons by-nc-sa). Přeložený článek vyšel původně na blogu překladatele.

Dobrá, mluvili jsme o tom proč potře­bu­jete specifikaci, co speci­fi­kace obsahuje a kdo by ji měl psát. Ve čtvrtém a posledním dílu této série se s vámi podělím o některé své rady, jak psát dobrou specifikaci.

Týmy píšící speci­fi­kace si nejčastěji stěžují na to, že speci­fi­kace nikdo nečte. A když specifikace nikdo nečte, tak lidé, kteří je píší, mají sklon být cyničtí. Je to jako ve starém komiksu s Dilbertem, kde inženýři použili deset centi­metrů tlustý štos speci­fi­kace pro přestavění své kancelářské kóje. Ve vaší typické velké a byrokra­tické firmě každý tráví měsíce psaním nudné speci­fi­kace. Jakmile je speci­fi­kace hotová, uloží se na polici, a nikdy se už nesundá. Produkt je imple­men­tován bez ohledu na speci­fi­kaci, kterou nikdo speci­fi­kaci nečetl, jelikož je tak ubíjející. Jenže samotný proces psaní speci­fi­kace mohl být dobré cvičení, které by alespoň každého přinu­tilo nad věcí se zamys­let. Ale fakt, že speci­fi­kace leží na polici (nepřeč­tená a nemilo­vaná), dává lidem pocit, že to bylo k ničemu.

Jakmile bude produkt doručen, začnou spory kvůli tomu, že speci­fi­kace nikdo nečetl. Někdo (mana­ge­ment, marke­ting nebo zákaz­ník) řekne: „Počkejte! Slíbili jste mi, že tam bude pařáček na mušle! Kde je pařáček na mušle?“ A programátoři řeknou: „Ne. Když se podíváte do speci­fi­kace do kapitoly 3, podka­pi­toly 2.3.0.1, uvidíte, že říká celkem jasně ‚žádný pařáček na mušle.‘“ To ale neuspo­kojí zákaz­níka, který má vždycky pravdu, takže nevrlí programátoři to musí dovybavit pařáčkem na mušle (což je učiní ještě cynič­tější ohledně speci­fi­kací). Nebo manažer řekne: „Hele, všechna ta slova v tomhle dialog boxu, to je moc ukecané. Nad každým by měl být nadpis.“ A frust­ro­vaní programátoři řeknou: „Ale ty jsi schválil speci­fi­kaci s přesným obsahem a rozvržením každého dialog boxu!“ Ale manažer samozřejmě speci­fi­kaci nečetl, protože když se pokusil, jeho mozek začal unikat skrz oční důlky a stejně to kolido­valo s jeho úterním golfem.

Takže speci­fi­kace jsou dobré, ale ne když je nikdo nečte. Jako autor speci­fi­kace musíte lidi přimět, aby vaše věci četli. Pravděpo­dobně byste se měli snažit nezpůsobit to, aby už tak malý mozek unikl skrz oční důlky.

Přimět lidi, aby četli vaše věci, je obvykle jen otázkou dobrého psaní. Ale nebylo by ode mě fér říct jen: „buďte dobrými spiso­va­te­li,“ a nechat to tak. Zde jsou čtyři jedno­duchá pravidla, která musíte násle­do­vat, abyste vytvořili speci­fi­kaci, která je čtena.

Pravidlo 1: Buďte vtipní

Jo, pravidlo číslo jedna. Abyste přiměli lidi číst vaši speci­fi­kaci, je nutné udělat z toho zážitek. Neříkejte mi, že jste se narodili nudní. To neberu. Každý má neustále zábavné nápady, jen je vyřadíme autocen­zu­rou, protože máme za to, že jsou „nepro­fe­sionál­ní“. Pche. Občas musíte porušit pravidla.

Pokud jste četli tu spoustu smetí, kterou jsem na svém webu napsal, jistě jste si všimli několika roztroušených chabých pokusů o vtip. Čtyři odstavce zpět jsem vtipkoval na tekutost těla a utahoval si z manažerů za hraní golfu. Ačkoliv ve skuteč­nosti nejsem tak vtipný, přesto se snažím být zábavný ve stylu smutného klauna. Píšete-li speci­fi­kaci, tak vhodné místo, kde být vtipný, jsou příklady. Pokaždé když potře­bu­jete říct příběh, jak funkce funguje, tak místo:

Uživatel stiskne Ctrl + N pro vytvoření nové tabulky Zaměst­nanec a začne zadávat jména zaměstnanců.

Napište něco jako:

Slečna Prasátko šťouchá do kláves­nice řasen­kou, protože její buclaté prsty jsou příliš tlusté, aby zmáčkly jednot­livé klávesy, stiskne Ctrl + N pro vytvoření nové tabulky Přítel a napíše jeden záznam „Kermit“.

Pokud jste četli, co napsal Dave Barry, zjistíte, že jeden z nejjed­no­dušších způsobů být vtipný je být konkrétní, i když to není potřeba. „Mrňaví mopsíci“ jsou vtipnější než „psi“. „Slečna prasátko“ vtipnější než „uživa­tel“. Místo „zvláštní účast­níci“ řekněte „levo­rucí pěsti­telé avokáda“. Místo: „Lidé, kteří odmítají uklízet po svých psech, by měli být potres­táni,“ řekněte, že by měli „být posláni do vězení tak osamělého, že vězni musí za sex platit pavoukům.“

Jo a pokud si myslíte, že je nepro­fe­sionální být vtipný, tak je mi líto, ale jen nemáte smysl pro humor. (Nepopírejte to. Lidé bez smyslu pro humor to vždycky popřou. Nemůžete mě oblafnout.) A pokud pracujte ve firmě, kde vás lidi budou méně respek­to­vat, když vaše speci­fi­kace bude svěží, vtipná a zábavná na čtení, tak jděte a najděte jinou firmu, protože život je sakra příliš krátký, abyste dny trávili na tak krutém a mizerném místě.

Pravidlo 2: Pište specifikaci jako kód, který vykoná mozek

Proč si myslím, že programátoři mají problémy psát dobrou specifikaci?

Píšete-li kód, vaším hlavním publikem je kompilátor. Jo, já vím, že lidé taky musí číst kód, ale obecně je to pro ně velmi obtížné. Pro většinu programátorů je dost těžké, aby dostali kód do stavu, kdy ho přečte kompilátor a správně ho inter­pre­tuje. Starat se o to, zda je kód i lidsky čitelný, je luxus. Když napíšete:

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 */ }

nebo

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

dosta­nete stejný výstup. Proto, pokud se nad tím zamys­líte, mají programátoři sklon psát něco jako:

Mějme funkci AddressOf(x), která je defino­vaná jako mapování z uživa­tele x na emailovou adresu (ANSI řetězec) daného uživa­tele podle speci­fi­kace RFC-822. Předpok­ládejme uživa­tele A a uživa­tele B, kdy A chce poslat e-mail uživa­teli B. Takže uživatel A iniciuje novou zprávu za použití nějaké techniky (ale ne všech) uvedené jinde a napíše AddressOf(B) do pole To:

To lze přeformulovat:

Slečna Prasátko chce jít na oběd, takže vytvoří nový e-mail a do políčka To: napíše Kermi­tovu adresu.

Technická poznámka: adresa musí být standardní inter­ne­tová adresa (podle speci­fi­kace RFC-822).

Oboje má teore­ticky stejný „význam“, až na to, že prvnímu příkladu není možné porozumět, dokud si ho pečlivě nedekódu­jete. Zato druhému příklad je snadné rozumět. Programátoři se často snaží psát speci­fi­kaci, která vypadá jako hutné vědecké pojed­nání. Myslí si, že „přesná“ speci­fi­kace potře­buje být „tech­nicky“ přesná a tím to hasne.

Chybou je, že když píšete speci­fi­kaci, tak kromě toho, že musí být přesná, musí být rovněž srozu­mi­telná. Což v programátorské hantýrce znamená, že musí být napsaná tak, aby ji lidský mozek mohl „zkom­pi­lo­vat“. Jeden z velkých rozdílů mezi počítačem a lidským mozkem je, že počítače jsou ochotné trpělivě sedět, dokud nedefi­nu­jete termíny, které chcete použít později. Ale lidé neporo­zumí tomu, o čem mluvíte, pokud je nejprve nemoti­vu­jete. Lidé nechtějí něco dekódo­vat. Prostě si to chtějí přečíst, aby tomu porozuměli. Lidem musíte poskyt­nout přehled a pak ho naplnit detaily. U počítač­ových programů začínáte pracovat s plným detailem od shora až dolů. Počítač nezajímá, zda jsou názvy proměn­ných smysluplné. Lidský mozek rozumí věcem lépe, když dokážete jeho mysli vykreslit živý obraz vyprávěním příběhu (i kdyby to měl být zlomek příběhu), protože naše mozky jsou vyvinuty právě pro porozumění příběhům.

Ukáže­te-li zkušenému šachis­tovi šachov­nici upros­třed hry, byť jen na vteřinu nebo dvě, okamžitě bude schopný si zapama­tovat pozice všech figur. Ale nesmyslně posuňte několik figur na místa, kam by se v normální hře nedostaly (například pěšec do první řady nebo oba černé střelce na černá pole), a bude pro něj mnohem obtížnější si šachov­nici zapama­tovat. Počítače myslí jinak. Počítačový program si může zapama­tovat možné i nemožné rozložení šachov­nice se stejnou lehkostí. Lidský mozek nepra­cuje způsobem náhod­ného přístupu, vyšla­pané cestičky mají sklon být naším mozkem zesíleny. Některým věcem je snazší porozumět, protože jsou běžnější.

Takže když píšete speci­fi­kaci, pokuste se předs­tavit si osobu, které je určená, a že chcete, aby pocho­pili každý krok. Větu za větou se sami sebe ptejte, zda v kontextu, který jste jim doposud dali, při čtení této věty věci do hloubky porozumí. Pokud někdo z vašeho publika neví, co to je RFC-822, tak to buď musíte defino­vat, nebo alespoň pohřbít do technické poznámky, aby manažeři, kteří budou speci­fi­kaci číst, to nevzdali hned, jak narazí na spoustu technic­kého žargonu.

Pravidlo 3: Pište co nejjednodušeji

Nepoužívejte strojený formální jazyk, protože si myslíte, že je nepro­fe­sionální psát v jedno­duchých větách. Použijte co nejjed­no­dušší jazyk, jaký můžete.

Lidé používají slova jako „uplat­nit“, protože si myslí, že „použít“ zní nepro­fe­sionálně. (Zas je tu to slovo „nepro­fe­sionál­ní“. Pokaždé, když vám někdo řekne, že byste něco neměli dělat, protože je to „nepro­fe­sionál­ní“, tak víte, že mu dochází oprav­dové argumen­ty.) Domnívám se, že ve skuteč­nosti si mnoho lidí myslí, že jedno­duché psaní znamená, že něco je špatně.

Rozdělte text do krátkých vět. Máte-li problém napsat větu čistě, tak ji rozdělte do dvou či třech kratších.

Vyhněte se textovým zdím: celé stránky jen s textem. Lidi to vyděsí a nebudou je číst. Kdy jste si naposled všimli populár­ního časopisu nebo novin s celost­rán­kovým textem? Časopisy jdou dokonce tak daleko, že vezmou citaci z článku a vytis­knou ji velkým písmem dopros­třed stránky. Používejte odrážky nebo seznamy, obrázky, grafy, tabulky a spoustu bílého místa tak, aby čtení vypadalo načančaně.

Časopisy jdou dokonce tak daleko, že vezmou citaci z článku a vytisknou ji velkým písmem doprostřed stránky. Používejte odrážky nebo seznamy, obrázky, grafy, tabulky a spoustu bílého místa tak, aby čtení vypadalo načančaně.

Nic nezlepší speci­fi­kaci víc než velká spousta snímků obrazo­vek. Obrázek může mít cenu tisíce slov. Kdoko­liv, kdo píše speci­fi­kaci pro software na Windows, by měl inves­tovat do licence Visual Basic a naučit se ho používat alespoň tak, aby byl schopný dělat mockupy obrazovek (Na Macu použijte REAL Basic; pro webové stránky Front Page nebo Dreamwea­ver). Zachyťte snímky obrazovky (Ctrl + Pr­tSc) a vlože je do své specifikace. (Text byl napsán v roce 2000 – pozn. red.)

Pravidlo 4: Několikrát si vše znovu přečtěte a revidujte

Původně jsem měl připra­vený dlouhý výklad tohoto pravidla, ale je prostě tak snadné a zřejmé. Přečtěte si speci­fi­kaci několikrát a revidujte. Jasné? Nalez­ne­te-li větu, které není úžasně jedno­duše rozumět, tak ji přepište.

Ušetřil jsem spoustu času nevysvět­lováním pravidla 4, takže přidám jiné pravidlo.

Pravidlo 5: šablony jsou škodlivé

Odolejte pokušení mít standardní šablony pro speci­fi­kace. Zpočátku si můžete myslet, že je důležité, aby „každá speci­fi­kace vypadala stejně“. Tip: Není. Jaký je v tom rozdíl? Vypadá každá kniha ve vaší domácí knihovně úplně stejně? Chtěli byste to?

Horší je, že máte-li šablony, přidáte do nich několik sekcí, o kterých si myslíte, že jsou důležité pro každou funkcio­na­litu. Napřík­lad: Velký Bill vydá nařízení, že od teď by měl mít každý Microsquish produkt inter­ne­tovou kompo­nentu. Takže šablona speci­fi­kace má teď sekci „inter­ne­tová kompo­nen­ta“. Kdykoliv někdo bude psát speci­fi­kaci, bez ohledu na to jak triviální, musí vyplnit tuto sekci, i kdyby zrovna psal speci­fi­kaci pro Microsquish klávesnici.

Sekce se hromadí a šablona začíná být pěkně velká. (Tady je ukázka velmi špatné šablony pro specifikaci. Kdo ve speci­fi­kaci potře­buje bibliog­rafii nebo glosář?) Problém takto velkých šablon je, že lidi vyděsí od psaní speci­fi­kace, protože to vypadá jako straši­delný úkol.

Speci­fi­kace je dokument, který chcete, aby lidé četli. V tom se nijak neliší od sloupku v The New Yorker nebo studentské práce. Už jste někdy slyšeli o profe­so­rovi, který by studentům rozdával šablony? Už jste někdy četli dva dobré eseje, které by šly napasovat do šablony? Zapomeňte na to.