Podcast na Szoftverdokumentáció és alapelvei

Přepis

Tomáš: ...szóval a világ legjobb programozója ír egy zseniális kódot, de ha egyetlen sor magyarázatot sem ír hozzá, akkor az gyakorlatilag semmit sem ér?

Karolína: Pontosan! Ez olyan, mintha feltalálnád a világ legjobb motorját, és aztán kidobnád a kézikönyvet. Senki sem fogja megjavítani, senki sem fogja továbbfejleszteni, és senki sem tudja, hogyan kell használni!

Tomáš: Ez egy szuper hasonlat! Üdvözlünk titeket a Studyfi Podcastben, ahol ma a szoftverfejlesztés világába merülünk el.

Karolína: Na is vágjunk is bele rögtön a közepébe. Rengetegen gondolják, hogy a kódba írt kommentek időpazarlás. „Hiszen tudom, mit írtam,” mondják maguknak.

Tomáš: Jaj, ismerős. „Az én kódom úgyis magától értetődő.” Persze…

Karolína: Pontosan. Csakhogy ez csak addig igaz, amíg el nem mész a projekttől egy hétre. Vagy elég egy szabadság. Aztán visszajössz, nézed a saját kódodat, és azt kérdezed, hogy mit is akart ezzel az író?

Tomáš: És közben az az író te magad vagy! Ez többször megesett velem, mint amennyit bevallanék.

Karolína: Mindenkivel megesik. És ez csak egy ok. A mai szoftver csapatmunka. A kommentek üzenetek a kollégáidnak, hogy tudjanak építeni a gondolatodra. Nélkülük ez szinte lehetetlen.

Tomáš: És mi van, ha a kódomat könyvtárként akarom használni másoknak? Tehát adok nekik egy eszközt, de nem mutatom meg nekik, hogyan működik pontosan belülről.

Karolína: Szuper észrevétel! Ebben az esetben a minőségi dokumentáció abszolút kulcsfontosságú. Enélkül a csodálatos könyvtárad gyakorlatilag használhatatlan lenne.

Tomáš: Rendben, szóval dokumentálni kell. Ez azt jelenti, hogy minden projekthez több száz oldalnyi szöveget kell írnom? Ez egy rémálomnak hangzik.

Karolína: Dehogyis! És ez a szép benne. A dokumentáció szintje projektenként változik. Ez nem dogma. Ez a hatékonyságról szól.

Tomáš: Hogy érted?

Karolína: Képzeld el, hogy egy kis csapatban dolgozol, mindenki egy szobában ül, és egy egyszerű appot fejlesztetek. A domain ismert. Ilyen esetben az architektúra dokumentációjához elég lehet egy fotó a táblára rajzolt vázlatról.

Tomáš: Tényleg? Csak egy fotó a mobilról?

Karolína: Pontosan. Miért ne, ha mindenkinek van értelme, és időt takarít meg? De most képzeld el az ellenkezőjét. Egy nagy, elosztott csapat, új, bonyolult technológia, ismeretlen terület... Ott már sokkal többre lesz szükséged.

Tomáš: Például egy fogalomtár, részletes modellek arról, hogyan kommunikálnak egymással a komponensek, és így tovább?

Karolína: Pontosan. A cél nem az, hogy a lehető legtöbb dokumentációt hozzuk létre, hanem a megfelelő dokumentációt az adott projekthez.

Tomáš: Rendben, tegyük fel, hogy egy bonyolultabb projektünk van. Mit kellene konkrétan rögzítenünk az architektúra dokumentációban?

Karolína: Néhány alapvető nézőpontot kell rögzítenünk a rendszerről. Először is, a statikus nézet – milyen részekből áll az alkalmazás. Ezt úgy képzelheted el, mint egy épület alaprajzát. Itt vannak az osztályok, itt vannak a csomagok.

Tomáš: Értem. És tovább?

Karolína: Másodszor, a dinamikus viselkedés. Tehát, hogyan kommunikálnak egymással az egyes részek. Ez olyan, mintha azt néznéd, ahogy az emberek az épületben szobáról szobára járnak. Ehhez kiválóan alkalmasak például az UML szekvencia diagramok.

Tomáš: És mi van a felhasználói nézőponttal? Őt ugyebár nem érdekli, milyen osztályaink vannak.

Karolína: Pontosan! Ez a harmadik kulcsfontosságú nézőpont. Erre szolgálnak az úgynevezett „use case”-ek, vagyis használati esetek. Ezek leírják, mit csinál a rendszer a felhasználó szemszögéből, milyen funkciókat kínál neki. Ez egy funkcionális nézőpont.

Tomáš: Szóval vannak különböző modelljeink, különböző nézőpontjaink... Nem fordulhat elő, hogy túl sok lesz belőle? Hogy végül elveszünk abban a dokumentációban?

Karolína: De, és ez óriási kockázat! Minél több dokumentációd van, és minél több helyen ismétled ugyanazokat az információkat, annál több munkád van a frissítésével.

Tomáš: És annál nagyobb az esélye, hogy valahol hiba vagy inkonzisztencia lesz. Egyik dokumentumban A verzió, a másikban B verzió.

Karolína: Pontosan! Ezért én személy szerint a minimalista, hatékony megközelítést preferálom. Léteznek nagyon tudományos módszerek is, például a Software Engineering Institute-tól, amik szinte külön tudományágként tekintenek a dokumentációra.

Tomáš: Szóval a kevesebb néha több, ha nem akarsz olyan dokumentációval végezni, ami hosszabb és bonyolultabb, mint maga a kód?

Karolína: Pontosan eltaláltad. A cél az érthetőség és a hatékonyság, nem pedig a papírhalmok.

Tomáš: Ez az egész rengeteg munkának hangzik. Vannak olyan eszközök, amik megkönnyítenék ezt a, valljuk be, néha kellemetlen munkát?

Karolína: Persze. Nem kell mindent kézzel írnunk. Vannak szuper eszközök, amik képesek a dokumentációt közvetlenül a forráskódból generálni. Például a Java-nak van egy JavaDoc nevű eszköze.

Tomáš: Szóval ha a kommenteket helyesen írom közvetlenül a kódba, akkor a program magától készít belőle egy szép dokumentációt?

Karolína: Pontosan! Ez az egyik leghatékonyabb módszer. Egy másik technológia, ami sokat segít ebben, az XML. De erről majd többet mesélünk legközelebb.

Tomáš: Rendben, szóval átbeszéltük a tervezést és a specifikációt... de most eszembe jut egy dolog, amit az általam ismert programozók imádnak. A dokumentáció.

Karolína: Ja, telitalálat! Megkérni egy fejlesztőt, hogy írjon dokumentációt, az olyan, mintha megkérnél egy macskát, hogy vegyen egy fürdőt. Egyszerűen nem akarják megcsinálni.

Tomáš: Ez egy szuper hasonlat! De miért is olyan fontos ez, ha mindenki ennyire utálja?

Karolína: Mert a szoftver sosem él vákuumban. Nem csak magunknak csináljuk. Képzeld el így... a karbantartó csapatnak tudnia kell, hogyan épül fel a rendszer, hogy meg tudja javítani. A tesztelőknek pedig tudniuk kell, pontosan mit kell tennie a rendszernek, hogy ellenőrizhessék, helyesen működik-e.

Tomáš: És persze az ügyfelek...

Karolína: Pontosan! Az ügyfeleknek felhasználói kézikönyvre van szükségük, hogy tudják, mire kattintsanak. Minden szerepkörnek más nézőpontra, más típusú információra van szüksége. A dokumentáció a híd közöttük.

Tomáš: Rendben, ennek van értelme. Szóval minden projekthez papírhalmokat és tucatnyi dokumentumot kell tartanunk?

Karolína: Dehogyis! És ez a kulcsfontosságú. Az agilis világban az a szabály, hogy a forma nem olyan fontos, mint a tartalom. Nem arról van szó, hogy méteres papírhalmok legyenek, hanem arról, hogy egyáltalán van-e információnk, és megosztjuk-e.

Tomáš: Szóval a kevesebb néha több?

Karolína: Pontosan. Egy kis csapatnál, ami egy szobában ül, és mindenki tudja, min dolgozik, elég lehet pár diagram a táblán és egy jól kommentált kód. Ezzel szemben egy hatalmas nemzetközi projektnél, ahol tucatnyi csapat dolgozik... ott már formálisabb és részletesebb dokumentációra van szükségünk.

Tomáš: Szóval a kontextustól függ. Nincs egy univerzális megoldás mindenkinek.

Karolína: Bingo! Pontosan erről van szó. A cél az, hogy *elegendő* dokumentációnk legyen, nem *maximális*. Hatékonyságot akarunk, nem bürokráciát.

Tomáš: Fasza, ezt értem. Vannak olyan eszközök, amik megkönnyítenék ezt a nem túl kedvelt munkát?

Karolína: Persze! A programozók okosak és lusták, szóval kitaláltak módokat, hogyan automatizálják ezt. Szuper példa erre a JavaDoc. Ez egy eszköz a Java nyelvhez.

Tomáš: Hogy működik?

Karolína: Egyszerűen. Írsz kommenteket közvetlenül a kódba bizonyos szabályok szerint. Aztán elindítod a JavaDoc eszközt, és az automatikusan generál neked egy szép, áttekinthető technikai dokumentációt HTML formátumban ezekből a kommentekből. Nem kell semmit kétszer írnod.

Tomáš: Ez szuperül hangzik! És mi van valami általánosabb szabványokkal? Valami olyasmi, mint... egy szakácskönyv a jó dokumentációhoz?

Karolína: Létezik. Például az IEEE 1063 szabvány. Ez lényegében azt mondja meg, hogy egy minőségi felhasználói dokumentációnak minimálisan mit kell tartalmaznia. Milyen struktúrája legyen, formátuma, hogy teljesnek, pontosnak kell lennie... Ez egyfajta útmutató, hogy semmi fontos ne maradjon ki.

Tomáš: Szóval nem kell újra feltalálnunk a kereket.

Karolína: Pontosan. Támaszkodhatunk a bevált gyakorlatokra.

Tomáš: Említetted, hogy a JavaDoc-kal nem kell kétszer írnunk a dolgokat. Ez a fő gondolat, nem?

Karolína: Határozottan! Az újrafelhasználás elve itt abszolút alapvető. Nem akarunk olyan dokumentumokat létrehozni, amik aztán csak hevernek. Megpróbáljuk felhasználni azt, amink már van.

Tomáš: Például mit konkrétan?

Karolína: Emlékszel, amikor a use case forgatókönyvekről beszéltünk, ahol leírjuk, hogyan lép interakcióba a felhasználó a rendszerrel? Például pénzfelvétel bankautomatából.

Tomáš: Ja, azok a lépések, amik történnek.

Karolína: Na, pontosan ezeket a szöveges forgatókönyveket veheted, kicsit módosíthatod őket, hozzáadsz pár képet, és máris kész egy fejezet a felhasználói kézikönyvbe. Rengeteg munkát spóroltál meg, és biztosítottad, hogy a kézikönyv megfelel az eredeti követelményeknek.

Tomáš: Hú, ez okos. Szóval a dokumentáció valójában nem is kell, hogy akkora rémálom legyen. Inkább az okos megközelítésről és a már meglévő dolgok felhasználásáról szól.

Karolína: Pontosan. Ez egy újabb darabja a szoftverfejlesztés kirakósának. És ha már a kirakósnál tartunk... a következő kulcsfontosságú darab maga az implementáció és a tesztelés, amire majd legközelebb térünk ki.

Tomáš: Takže jsme probrali, jak HTML dává strukturu webu pro lidi. Ale co když potřebujeme, aby i počítače rozuměly významu těch dat?

Karolína: Pontosan, Tomáš! És pontosan itt lép színre az XML, vagyis az Extensible Markup Language.

Tomáš: Kiterjeszthető jelölőnyelv... Ez fontosnak hangzik.

Karolína: Az is! Képzeld el így... az XML-ben saját, teljesen specifikus jelölőket, úgynevezett tageket hozhatsz létre. Így az általános tag helyett van például <autor>, <nazev> vagy <verze>. Azonnal tudod, miről van szó.

Tomáš: Aha! Szóval az adatok maguk hordozzák a leírásukat. Ez abszolút szuper lehet a kereséshez és a gépi feldolgozáshoz.

Karolína: Pontosan! De ezzel a szabadsággal nagy felelősség is jár. Az XML-nek ugyanis sokkal szigorúbb szabályai vannak, mint a HTML-nek.

Tomáš: Milyen szabályok például? Semmi elfelejtett záró tag?

Karolína: Semmi esetre sem! Minden tagnak párosnak kell lennie. Ráadásul az XML megkülönbözteti a nagy- és kisbetűket, szóval a <Tag> és a <tag> két teljesen különböző dolog.

Tomáš: Értem, érzékeny a kis- és nagybetűkre. Mi van még?

Karolína: Minden dokumentumnak pontosan egy gyökéreleme kell, hogy legyen, ami mindent beburkol. És az attribútumok értékeinek mindig idézőjelben kell lenniük. Nincsenek kivételek.

Tomáš: Majdnem... matematikailag pontosnak tűnik. De honnan tudja a rendszer, hogy melyik struktúra a helyes?

Karolína: Szuper kérdés! Ehhez DTD-t vagy úgynevezett XML Sémát használnak, amik meghatározzák az engedélyezett struktúrát. De erre mindjárt rátérünk.

Tomáš: Rendben, tényleg sokat átbeszéltünk. De még van előttünk egy utolsó nagy téma... a Java. És főleg, hogyan ne vesszünk el a saját kódunkban.

Karolína: Pontosan! És ez elvezet minket valamihez, amit Javadoc-nak hívnak. Ez egy hihetetlenül hasznos eszköz a Sun Microsystemstől.

Tomáš: Javadoc... majdnem valami törvénynek hangzik. Mit csinál pontosan?

Karolína: Képzeld el így. Ez egy olyan eszköz, ami automatikusan generál egy weboldalt dokumentációval, közvetlenül a forráskódodban lévő kommentekből. Az API dokumentációhoz ez egy abszolút életmentő.

Tomáš: Szóval írok egy kommentet, és az egy professzionálisan kinéző weboldal része lesz? Ez szuper.

Karolína: Alapvetően igen! De van egy bökkenő. Az eszköz ugyan okos, de nem tud gondolatot olvasni. Ha az osztályodat például 'Pr'-nek nevezed el, és nem írsz érthető kommenteket, a végeredmény dokumentáció semmit sem fog érni.

Tomáš: Világos. Szemét be, szemét ki. Szóval automatizálja a formázást, de a tartalom minősége még mindig rajtad múlik.

Karolína: Pontosan. Segít neked felépíteni egy házat, de a téglákat magadnak kell beszerezned. A jó kommentek és az értelmes nevek az alapok.

Tomáš: Ez egy tökéletes záró gondolat. A jó szokások kulcsfontosságúak. Karolína, mára ennyi. Átmentünk mindenen az XML sémáktól a Javáig. Nagyon köszönjük, hogy mindezt tisztáztad nekünk.

Karolína: Örömmel tettem! Köszi a meghívást.

Tomáš: És köszönjük mindenkinek, hogy velünk tartott a Studyfi Podcasten. Halljuk egymást legközelebb!