Frontend dokumentálás

homer-simpsonEddigi tapasztalataim alapján a webfejlesztők jobban szeretnek pizzát enni mint dokumentációt írni (cáfoljon meg aki nem ért egyet). Ezzel szemben a dokumentációnak a fejlesztés és a későbbi módosítások során jelentős szerepe van – vagy kellene lennie. Ma reggel feltaláltam egy egyszerű, gyors és hatékony dokumentációs eljárást. Persze lehet, hogy a módszer 30 éve létezik és én csak újrafeltaláltam de ez jelen pillanatban teljesen közömbös a számomra.

A webfejlesztők első törvénye kimondja, hogy a fejlesztő utál dokumentációt írni. Az első törvény miatt sokféle módszert kitaláltak már, amivel meg lehet magyarázni, hogy miért ne írjuk dokumentációt. Az egyik ilyen, hogy egy jól szervezett objektum önmagát dokumentálja. A másik, hogy a programtervezési minták és pár forrásbeli megjegyzéssel elegendő dokumentálni. Hát bizonyos esetekben elképzelhető, hogy ezek a megközelítések többé-kevésbé működőképesek, de a frontend fejlesztés során biztosan nem az.

E mellett ha nincs dokumentáció akkor szívás van, szóval valami csak kell.

Jómagam funkcionális programozási előélettel kerültem az objektum orientált valamint az eseményvezérelt programok harcmezejére. Többször visszatért az a probléma, hogy pár hónap távlatából a felhasználói felületet látva és mellérakva az azt vezérlő JavaScript kódot, jó ideig eltartott mire újra felidéztem, hogy mi miért és hogyan. Teljesen biztos vagyok benne, hogy léteznek jól működő esemény orientált dokumentációs formák de én eddig egyet sem használtam és mások fejlesztésiben sem láttam sok nyomát, hogy használták volna.

A világmegváltó ötlet az volt, hogy csináljunk egy screenshot-ot az alkalmazás kérdéses darabjáról, jelöljük meg rajta az eseményekre reagáló objektumokat és jelöljük, hogy az adott esemény bekövetkezésekor melyik függvény fut le.

Ennek eredményeként az alábbihoz hasonló képet fogunk kapni.

Egy ilyen kép remek emlékeztetőül szolgál ha ismét hozzá kell nyúlni a kódhoz. Látszik, hogy mely elemekkel dolgozunk, mi mire reagál, milyen esemény melyik függvényt fogja meghívni.

Te hogyan csinálod?

2 thoughts on “Frontend dokumentálás

Vélemény, hozzászólás?

Az email címet nem tesszük közzé. A kötelező mezőket * karakterrel jelöljük.