Joel a szoftverről szoftvermenedzsment egyszerűen

Joel lapja

Gerilla magyar fordítások

Hivatalos fordítások

4. rész: Tippek

Írta: Joel Spolsky (2000. október 15.)
Fordította: Plesz Gábor
Lektorálta: Nagy Balázs
Az eredeti cikk

Rendben van, beszéltünk arról, hogy miért van szükséged a specifikációra, mi is van benne, és kinek kell írnia. A sorozatnak ebben a negyedik és utolsó részében megosztok néhányat a tanácsaimból a jó specifikáció írással kapcsolatban.

A leggyakoribb panasz, amit azoktól a csapatoktól hallok, akik írnak specifikációt, hogy „senki sem olvassa el”. Ha senki sem olvassa el, akkor azok, akik írták, némiképpen hajlanak a cinizmusra. Ez olyan, mint a régi Dilbert karikatúra, ahol a mérnökök tíz centi vastag specifikációkat használnak az uszoda öltözőjének a bővítéséhez. A te tipikus nagy, bürokratikus cégednél mindenki hónapokat és hónapokat tölt unalmas specifikációk írásával. Ha egy elkészül, akkor felmegy a polcra, és soha többet nem jön onnan le többet, és a termék valami kacatból készül, tekintet nélkül arra, hogy mit mond a specifikáció, mivel senki nem olvassa a specifikációt, mert az annyira agyzsibbasztó. Maga a specifikáció írásának folyamata lehet, hogy egy jó edzés, mert mindenkit legalább ösztönöz arra, hogy végiggondolja a problémákat. Mindenesetre az tény, ha a polcra kerülő (olvasatlan és utált) specifikáció elkészül, olyan érzést kelt az emberben, hogy egy csomó munkát a semmiért kellet elvégezni.

Tehát, ha a specifikációdat soha sem olvassák el, akkor néhány szurkálódást azért fogsz kapni, amikor a termék szállítása megtörténik. Valaki (főnök, marketinges, vevő) azt mondja: „egy pillanat. Azt ígérted, hogy teszünk bele egy Mászó Gőzhajót! Hol van a mászó gőzhajóm?” És a programozó azt mondja: „nem, valójában, ha megnézed a 3. fejezet 4. alfejezetének 2.3.0.1. bekezdését, akkor a következő teljesen egyértelmű mondatot látod: nem kell mászó gőzhajó”. De ezzel nem lesz elégedett a vevő, akinek mindig igaza van, így aztán a mérges programozó nekiállhat visszagyömöszölni a mászó gőzhajót a dologba, (sokkal inkább cinikussá válva a specifikáció iránt). Vagy a főnök mondja, „hé, minden megfogalmazás ezeken a dialógusablakokon túlságosan szószátyár, különben is minden dialógusablak tetejére kell még egy reklám”. És a programozó enyhén frusztrálva mondja „de hát te engedélyezted a specifikáció alapján a kódolást, és ott minden dialógusablak kinézete és tartama pontosan fel van sorolva”! Természetesen a főnök valójában nem olvasta, mivel amikor megpróbálta, az agya elkezdett elszivárogni a szemgödrein keresztül, és különben is ütközött a keddi golfmeccsével.

Vagyis a specifikáció nagyon jó dolog, kivéve, ha senki sem olvassa. Specifikáció íróként cselesen rá kell venni az embereket, hogy olvassák el amit írtál, és meg kell próbálnod, hogy az erőfeszítésük miatt nehogy az egyébként sem túl sok agyuk kifollyék a szemgödreiken.

Cselesen olvasásra bírni az embereket valójában csak a jó írás dolga. De nem lenne fair tőlem, ha csak annyit mondanék, „légy jó író”. Ezért írtam le négy észerű szabályt, amit feltétlenül követned kell ahhoz, hogy olvasható specifikációt írj.

1. szabály: légy vicces

Igen, az első számú szabály az emberek cseles rábeszélésében a specifikációd olvasásához az az, hogy tedd élvezetes élménnyé. Ne mond azt nekem, hogy nem születtél vicces embernek, nem veszem be. Mindenkinek mindig vannak tréfás ötletei, csak az öncenzúrázza őket, mivel azt gondolja róluk, hogy „túl amatőr”. Ugyan már! Néha meg kell szegni a szabályokat.

Ha elolvasod weboldalamra összehordott nagymennyiségű szemetet, biztosan észrevetted, hogy néhány hülyeséget mindenhova elszórtam. Négy bekezdéssel ezelőtt egy durva folyós-test tréfát eresztettem el, és kifiguráztam a főnököket, amiért golfoznak. Bár valójában nem vagyok ennyire vicces, mégis folyamatosan próbálkozom, és ha a vicceléssel próbálkozó kapálózásaim önmagukban is szórakoztatóak, már megérte. Ha specifikációt írsz, a legkönnyebben a példáknál tudsz valami vicceset írni. Minden esetben, ha arról kell beszélned, hogy egy tulajdonság hogyan működik, ne ezt mondd:

• A felhasználó Ctrl+N-t nyom az új tábla létrehozásához és elkezdi az alkalmazottak felvitelét.

Írj valami ilyesmit:

• Miss Röfi a billentyűzetet szemceruzájával piszkálva, mivel a kis pufók ujjaival nem tud külön billentyűket megnyomni, leüti a Ctrl+N-t, hogy létrehozza az új Udvarlók táblázatát és az első sorba beírja: „Jancsi”.

Ha Dave Barry-t olvasol, akkor felfedezed, hogy az egyik legegyszerűbb módszer a tréfálkozáshoz, ha senkit sem nevezel a nevén. A „hiányos virslik” tréfásabb kifejezés, mint a „kutyák”. „Miss Röfi” tréfásabb, mint a „felhasználó”. A „különös érdeklődésű” helyett használj inkább „balkezes avokádó-földműves”-t. Ahelyett, hogy azt mondanád, „az emberek, akik nem takarítanak fel, miután a kutyájukat kellett volna megbüntetni”, mondd azt, hogy „ezeket olyan magányos rabhoz kell küldeni, aki még a póknak is fizetne a szexért”.

Ó, és igen, ha azt gondolog, hogy a viccelődés amatőr dolog, akkor sajnálom, de neked egyszerűen csak nincs humorérzéked. (Ne tagadd le. Az emberek, akiknek nincs humoroérzékük, mindig letagadják. Nem tudsz bolonddá tenni.) És ha olyan helyen dolgozol, ahol az emberek kevésbé becsülnek, mivel a specifikációid frissek, tréfásak és kellemes olvasni őket, akkor menj másik céghez dolgozni, mivel az élet olyan átkozottul rövid, hogy nem érdemes a napfényes óráidat zord és boldogtalan helyen töltened.

2. szabály: Specifikációt írni olyan, mint az agy számára végrehajtandó kódot írni.

Itt jön az, amiért azt gondolom, hogy a programozóknak a jó specifikáció írásával problémáik vannak.

Ha kódot írsz, akkor az elsődleges közönséged a fordítóprogram. Igen, tudom, hogy az emberek is el tudják olvasni a kódot, de ez nekik rettenetesen nehéz dolog. A legtöbb programozó számára pont elég a kódot olyan állapotba hozni, amit a fordító fel tud dolgozni, és pontosan tud értelmezni. Arra figyelni, hogy könnyen olvasható legyen emberek számára is, az egy luxus. Ha ezt írod:

void print_count( FILE* a, char * b, int c ){
    fprintf(a, "van %d %s", c, b);}
main(){
int n; n =
10; print_count(stdout, "alkalmazott", n) /* kód szándékosan elbonyolítva */ }

vagy

printf("van 10 alkalmazott\n");

ugyanazt az eredményt kapod. Ez az amiért, azt gondolom, hogy a programozók hajlanak arra, hogy ilyesmiket írjanak:

Legyen a Címe(X) fügvény úgy definiálva, hogy az X felhasználó az RFC-822 szabványban meghatározott elektronikus-levélcímét adja vissza ANSI szövegként. Legyen A és B felhasználó, ahol A egy elektronikus levelet akar B-nek küldeni. Ezért A tetszőleges (de nem bármilyen) máshol definiált technikával létrehoz egy új üzenetet, és beírja a Címe(B) értéket a Címzett: szerkesztőmezőbe.

Pedig ezt így kellene specifikálni:

Miss Röfi ebédelni szeretne menni, így kezd egy új email-t, és beírja Jancsi címét a "Címzett:" dobozba.

Technikai megjegyzés: a cím szabványos Internet cím (megfelel az RFC-822 szabványnak)

Mindkettő ugyanazt „jelenti” elméletileg, kivéve, hogy az első példát lehetetlen anélkül megérteni, hogy az ember gondosan dekódolja, míg a második példa megértése egyszerű. A programozók gyakran megpóbálják a specifikációikat akadémiai székfoglaló bonyolultságúra megírni. Azt gondolják, hogy a „hibátlan” specifikációhoz az a fontos, hogy „technikailag” hibátlan legyen, és azzal kész.

A tévedés az az, hogy a hibátlanságon kívül még megérthetőnek is kell lennie, vagyis, programozói szóhasználattal úgy kell írni, hogy az emberi agy „le tudja fordítani”. A számítógép és az emberi agy között az egyik nagy különbség, hogy a számítógép türelemmel meg fogja várni a fogalmak definiálását, amit később akarsz használni. Az emberek azonban motiváció nélkül nem akarják megérteni, miről beszélsz. Az emberek nem akarnak valamit dekódolni, hanem egyszerűen csak el akarják olvasni, és megérteni. Az emberek számára először egy vázlatot kell rajzolni, és aztán a részleteket kitölteni. A számítógépes programoknál elkezdi az ember az elejéről, és dolgozik a maga útján a végéig, folyamatosan teljes részletességgel. A számítógépet nem érdekli, hogy egy változó neve mennyire érthető elnevezés. Az emberi agy sokkal jobban érti a dolgokat, ha először egy élénk képet rajzolsz az elméjébe egy történet elmesélésével, akkor is, ha ez csak a töredéke a történetnek, mivel az elménk történetek megértésére fejlődött.

Ha a sakktáblát nézzük egy igazi játszma közepén, a tapasztalt sakkjátékosok akár egy vagy két másodperc alatt meg tudják jegyezni az állás minden részletét. De ha darabokból néhányat szabálytalan módon átmozgatunk (például néhány gyalogot az első sorba teszünk, vagy mindkét fekete futót fekete mezőre állítunk) sokkal, de sokkal nehezebb lesz nekik a táblát memorizálniuk. Ez más, mint ahogy a számítógép gondolkodik. A számítógép a lehetséges és a lehetetlen állásokat is egyfoma könnyen megjegyzi. Az emberi agy nem véletlen hozzáféréssel dolgozik; gyalogösvények mélyítik el a kapcsolatokat, és néhány dolgot sokkal könnyebb megérteni, mint másokat, mivel ezek sokkal mindennaposabbak.

Ezért, ha specifikációt írsz, próbáld meg elképzelni a személyt, aki majd olvasni fogja, és próbáld meg elképzelni, hogy mit fog mindenlépésnél ahhoz kérdezni, hogy megértse. Mondatról mondatra, kérdezd meg magadtól, ha ez az ember elolvassa ezt a mondatot, vajon megérti-e teljesen, abban az összefüggésben, ahogy elmondtad neki. Ha a célszemélyek közül valaki nem tudja, hogy mi az az RFC-822, vagy definiálnod kell, vagy, sokkal inkább elásni az RFC-822 említését is egy technikai megjegyzésbe, így a menedzser-típusok, akik olvassák a specifikációt, nem fogják eldobni és befejezni az olvasást az első pillanatban, ahogy egy szakzsargon kifejezést meglátnak.

3. szabály: Írj olyan egyszerűen, amennyire csak lehetséges

Ne használj dagályos és formális nyelvet, mert azt gondolod, hogy szakszerűtlen egyszerű mondatokat írni. Használj olyan egyszerű nyelvet, amilyet csak tudsz.

Az emberek csak azért használják a „használ” helyett a „alkalmaz” szót, mert azt gondolják a „használ” szakszerűtlen. (Megint ez a szó: „szakszerűtlen”. Mindig, amikor valaki ezt mondja neked, biztos lehetsz benne, hogy a valódi érvei elfogytak.) Tulajdonképpen sok ember gondolja úgy, hogy egyszerűen és tisztán írni és fogalmazni az valami rossz dolog.

Vágd szét a dolgokat rövid mondatokra. Ha problémát okoz egyszerűen leírni egy mondatot, vágd szét két vagy három felé.

Szüntesd meg a betűrengeteget: ahol az egész oldal csak szöveg. Az emberek megrémülnek és nem olvassák el. Mikor láttál utoljára egy népszerű magazinban egy teljes oldal szöveget? A magazinok kiragadnak egy idézetet a cikkből és óriási betűvel a lap közepére nyomtatják csak azért, nehogy egy teljes oldalon csak szöveg legyen. Használj számozott vagy pontozott listákat, képeket, grafikonokat, táblákat és egy kevés üres helyet, mert így az olvasás könnyebbnek „tűnik”.

Semmi sem erősíti a specifikációt annál jobban, mint rengeteg és még több képernyőkép. Akárki, aki Windows-hoz ír specifikációt, fektessen be a Visual Basic-be, és tanulja meg legalább annyira, hogy képernyő-modelleket tudjon készíteni. (Mac-hez használj REAL Basic-et (Nekem a command-ctrl-shift-3, Preview, New from clipboard (command-n), Export… (command-shift-e) jobban bejött – a lektor); Web oldalakhoz Front Page-et vagy Dreamweaver-t. Ezután fényképezd le a képernyőket (Ctrl+PrtSc), és illeszd be őket a specifikációdba.

4. szabály: A végén olvasd újra és nézd át néhányszor

Ja igen, szóval eredetileg ide egy hosszú és fontos szabályt terveztem, de ez a szabály sajnos túl egyszerű és nyílvánvaló. Olvasd át és nézd át a specifikációt néhányszor, rendben? Ha találsz olyan mondatot, ami nem szuper fantasztikusan könnyen megérthető, írd át.

Olyan sok időt takarítottam meg azzal, hogy a 4. szabályt nem ragoztam túl, hogy még egy szabályt kell mondanom.

5. szabály: A sablonok kártékonyak

Ne használj a specifikációidhoz áltlános sablont. Talán először azt gondolod, hogy az a fontos, hogy „minden specifikáció ugyanúgy nézzen ki”, de nem. Miben segít a különbözőség? A saját könyvespolcodon ugyanúgy néz ki minden könyv? Szeretnéd, hogy így legyen?

Ellenkezőleg, ha sablonjaid vannak, akkor egy csomó kötelező fejezetet adsz hozzá a sablonodhoz, amiről azt gondolod, hogy mindenhez fontos. Például: Nagy Béla úgy döntött, hogy mostantól kezdve minden Microquish terméknek tartalmaznia kell Internet összetevőt. Így aztán most a sablonnak van egy „Internet Összetevő” fejezete. Akármikor akárki specifikációt ír, nem számít milyen egyszerűt, meg kell töltenie egy „Internet Összetevő” fejezetet, akkor is, ha éppen a Microquish Billentyűzet specifikációját készíti. (És csodálkoztál, hogy miért szaporodik gombaként az Internet vásárlás gomb a billentyűzeteken.)

Hogy összefoglaljam a fejezetet, a sablon kicsit hosszú lett. (Itt egy példa a nagyon, nagyon rossz specifikáció sablonra. Kinek kell bibliográfia a specifikációba? Mi az ördögnek? Vagy szójegyzék?) A probléma az ilyen hosszú sablonnal, hogy elriasztja az embereket a specifikáció írástól, mert fölösleges munkának néz ki.

A specifikáció egy olyan iromány, amit az emberek el akarnak olvasni. Ebből a szempontból nem különbözik egy New York Times cikktől, vagy egy irodalom fogalmazástól. Hallotál már olyanról, hogy a tanár sablont ad a fogalmazáshoz? Olvastál már jó fogalmazást, ami illett volna egy sablonba? Felejtsd csak el.