dotNETportal.cz

Dobrý den, předem se omlouvám pokud tady takový článek už je, ale já jsem na něj bohužel nenarazil.

Myslím si že by bylo přínosné napsat článek o tom, jak se správně píše dokumentace a dělají vývojové diagramy k aplikaci. Já si k aplikaci sice pozámky dělám, ale nevím jestli obsahují všechny informace, jsou správně uspořádané atd. A u složitějších aplikací je dokumentace nezbytná, protože z vlastní zkušenosti vím, že pokud se potřebuji po půl roce k něčemu vrátit, musím složitě zjišťovat logiku daného modulu (a to nemluvím o tom, kdyby po mě měl nedej bože převzít údržbu aplikace někdo jiný) :)

Musím nesouhlasit. Vývojové diagramy jsou skvělá věc, často nejsrozumitelnější způsob jak objasnit základní logické principy nějaké části aplikace. Je ale jasné, že dělat je pro samotný kód a rozepisovat v něm jednotlivé podmínky, cykly atp. zbytečné je.

tiez vidim cestu skor v tom, ze jednoduchy komentar k triedam a vhodne pomenovanie metod (procedur) je niekedy viac ako rozsiahle dokumentacie, systemove prirucky ...

Tiez sa priklanam k nazoru, ze prehladnost a dobra citalelnost kodu sa da zabezpecit efektivnejsie, bez nutnosti produkovat hrby dokumentacie. (samo sebou ze niekedy je potrebne dokumentaciu vytvarat)

My vo firme používame na vytváranie dokumentácie program NDoc, ktorý z XML komentárov vycompiluje dokument windows helpu alebo vygeneruje html help, ktorý sa môže celý rovno pastnúť na internet.

Príklad poznámkovania z poznámkovania kódu

''' -----------------------------------------------------------------------------
''' <summary>
''' Metoda zapise chybovu/logovu hlasku do databazy ak tam este neexistuje.
''' Ak je nastavena premenna mySendMail na True rozposle sa sprava na
''' maily, ktorych adresy su zapisane v H__Konfiguracia
''' </summary>
''' <param name="type">Log/Chyba</param>
''' <param name="name">Nazov spravy</param>
''' <param name="description">Popis spravy</param>
''' <param name="entitaType">Typ entity</param>
''' <param name="entitaCode">Kod entity</param>
''' <param name="from">Odkial</param>
''' <param name="fromUser">Od uzivatela s kodom</param>
''' <remarks>
''' </remarks>
''' <history>
''' [vaclav] 3. 4. 2008 Created
''' </history>
''' -----------------------------------------------------------------------------

Časem se lze jistě naučit psát "sebedokumentující se" kód. Osobně jsem k tomu ale dospěl až v situaci, kdy jsem - jak říkáte - se nevyznal ve vlastním kódu po pár měsících, což je ostuda. Praxe je klíčová, to se nedá naučit, to se musí cítit.