A máme tu pokračování inspirované poslechem audio záznamů z jOpenSpace konference. Již jsem psal o ORM a nyní mé poznámky k tématu Dokumentace. Toto téma mě opravdu hodně zajímalo, protože jsem měl dojem, že na našem projektu dokumentace moc nevzniká a hrozně mě zajímalo, jak to dělají druzí.
V podstatě vývojářskou dokumentaci neděláme žádnou, takže pro nováčka může být dost obtížné se v kódu zorientovat. Proč to tak je? No v podstatě se snažíme psát přehledný a jasný kód, což je pohlídané především systémem review, který používáme (o něm více v příštím příspěvku). Navíc je to vše umocněno skutečností, že mé schopnosti orientovat se v kódu jsou nadstandardní a protože podle sebe soudím tebe, myslím si, že to dovedou všichni. Ve výsledku se ukazuje, že to chvilku trvá, ale ve výsledku je struktura aplikace poměrně dobře pochopitelná. Hlavním problémem stejně zůstává skutečnost co aplikace dělá a proč, a o tom bych dokumentaci psal hodně nerad, protože by to bylo na hrozně dlouho.
Byl jsem potěšen, jak i v tomto ohledu je tvorba naší dokumentace v souladu s okolím. Především pro uživatelskou dokumentaci používáme DocBook, který v poslední době editujeme pomocí XMLMindu. A nyní se začínáme malinko odlišovat. Obecně se hovoří o různých způsobech převodu DocBooku do výstupního formátu. Zde jsme šli standardní cestou a tou je XSLT transformace, kterou získáváme jak manuál v HTML tak v PDF (přes FOP). Protože jsme si vybrali jenom podmnožinu DocBooku, kterou podporujeme, máme vlastní šablony, které nejsou komplikované a vše funguje ke 100% spokojenosti. Konfigurace fontů, která byla zmiňovaná jako komplikovaná, zas tak složitá není (v porovnání např. s iTextem je srovnatelně složitá).
Samozřejmě FOP má své mouchy a nedostatky, ale současné verze se od 0.20.5 liší a dosahují uspokojivých výsledků. Navíc se FOP docela vyvíjí a každá nová verze je lepší než ta předchozí.
Jako podpora nanáviděných formátu od nejmenované firmy, bylo zmíněno, že uživatelé stejně vyžadují Wordový dokument, který umějí zpracovat a proto nejde DocBook použít. To není pravda, protože převod DocBooku do RTF není problém a pak pomocí revizí zanést změny zpět do DocBooku také není složité.
Z diskuse je zřejmé, že s dokumentací se bojuje všude a najít vyvážení mezi dost a né příliš záleží projekt od projektu. Ale obecně platí, čím více dokumentace jsme schopní vygenerovat na základě jednoho zdroje (ať už je jím DocBook, kód, UML model atd.) tím lépe pro všechny zúčastněné. Jakmile začneme přepisovat myšlenky z UML, či z kódu do dokumentace je to cesta do pekel, dřív nebo později se dokumentace rozejde s originálem (a když se nerozejde, bude nás to stát velmi vysoké úsilí).
Příspěvky
Using data replication in legacy displacement
Před 1 týdnem
9 komentářů:
S tímhle názorem více méně souhlasím a defakto to více méně reprezentuje takový obecný konsenzus přítomných.
Dost se tam zvažovala WIKI pro high level programátorskou dokumentaci. Obezně ale nesouhlasím s tím, že Javadoc a kód jako programátorská dokumentace postačuje. Je podle mého nutností mít někde zanesený koncept a myšlenky, které se za API skrývají. Ať už ve formě UML modelu (a zde ne jen ve čtverečkách a linkách, ale v dostatečném popisu v description) a / nebo prostým textem shrnujícím koncept dané knihovny / aplikace.
Pro budoucí porozumění a udržení jednotnosti / směru vývoje považuju tenhle druh dokumentace za nejcennější, přestože může být poměrně tenký. Za detaily totiž už můžeme jít do javadocu nebo do kódu. Nejdřív ale musíme vědět co a proč hledáme.
Btw. dost by mě zajímaly zkušenosti s používáním toho DocBooku ve vaší firmě. Já jsem toto, kdysi zprovozňoval u předchozího zaměstnavatele a byla to docela bolest. Oproti wordu / wiki ale vidím dost velké výhody. Problém je v tom, že ty exporty z toho lezly fakt docela ošklivé a customizace šablon mi zase tak jednoduchá nepřišla.
Prostě mi přijde, že na pořádné zprovoznění DocBooku - aby se používal jednoduše a měl alespoň trochu profesionální výstupy je na začátku potřeba poměrně znatelná časová investice.
Zajímaly by mě vaše zkušenosti a popř. třeba možnost většího nakouknutí do kuchyně - třeba to nakonec nebude tak složité, jak to na první pohled vypadá.
No tak s tim o psani dokumentace do kodu moc nesouhlasim. Bez popisu co ma dana metoda vykonat, jaky maji vstupni hodnoty vyznam a co se ocekava na vystupu je jenom otazkou casu, kdy nebude nikdo vedet co to vlastne dela.
Ani ten nejprehlednejsi kod v tom nepomuze, kdyz zakaznik (a to je zcela bezne) upravuje sve pozadavky a do mnohdy obskurdnich smeru.
Takovy kod, se bez znalosti kontextu neda vubec cist a i se znalosti to neni snadne, protoze nektere zmeny jsou delane na rychlo a do "business" dokumnetace nebyly zanesene.
Kdyz neni vyznam promene zdokumentovany, tak nikomu pak nedela problem, aby zamenil vyznam promenych (z jednoho slova neni vetsinou uplne zrejme k cemu to slouzi)
To honza novotný: Z DocBooku jsme si vybrali podmnožinu, která plně postačuje pro naše účely, tj. žádné tabulky a podobné věci. Z těch složitejších věcí jenom seznamy, obrázky a odkazy.
Následně pro převod do HTML (rámy - v jednom okně obsah a v druhém nápověda) a do PDF jsme vytvořili XSLT transformace a pro převod do PDF jsme použili zdroj výstup transaformace v XSL-FO a FOP.
Takže máme úhrnem 4 transaformace (3 pro HTML výstup a jednu pro PDF) o celkovém rozsahu 300 řádek pro HTML a 300 řádek pro PDF. Výstup mi přijde dost na úrovni (číslování kapitol, stránek, odkazy na čísla stránek s kapitolami apod). Vše vygenerujeme při buildu pomocí ant scriptu, který čítá 35 řádek.
Pohledu blíže do kuchyně se samozřejmě nebráním, ale nevím co si pod tím představit. Možná lépe se domluvit přímo po mailu ...
Plně si uvědomuji, že kód v podstatě nemáme dokumentovaný, ale zatím jsem nenašel nástroj, který by mi dokumentování umožnil tak jak bych si představoval. Jediné co pro mě má význam a cenu je vzít existující kód (i s doplněnými tagy či informacemi pro toto generování) a z něj něco vygenerovat, všechno ostatní je ztráta času, protože dřív nebo později přijde den, kdy se dokumentace rozejde s kódem a to je lepší ji nemít.
Aby byl kód přehledný, měl hlavu a patu, byl dokumentovaný a dokumentovaný správně, proto používáme review každého řádku, který do codebase napíšeme. A samozřejmostí jsou testy, které se u nás blíží na kritických částech 95% a na běžném novém kódu 80%. To jsou věci, které mi napomáhají věřit tomu co z nás vypadne (jako funkční aplikaci).
No, pokud mate takove pokryti testy, ktere jsou kvalitni, tak si myslim, ze uplne bez dokumentace vas kod neni. Sam prosazuji testy jako cast dokumentace, ze ktere je videt vzorove pouziti metod.
Právě jsem našel následující http://java.dzone.com/articles/reverse-engineer-source-code-u a vypadá to hodně slibně, vyzkouším ...
Ja nesouhlasim - naopak si myslim, ze bez dokumentace snad ani neni mozne velky software psat.
My vedeme vlastni TWiki a ke kazde pridavane vlastnosti mame analyzu a design. Podle toho se da alespon castecne (podle toho, jak je ten design up-to-date) zorientovat v logice kodu, ktery je potreba predelavat.
Samozrejme je problem, ze ty designy a analyzy postupem casu starnou a nereflektuji skutecnost.
Ale kazdopadne je to lepsi nez nic. Minimalne tam clovek nalezne informaci, ve kterem Mavenim modulu ma vubec danou funkcionalitu hledat a ktere jsou dulezite tridy, aby se mel alespon od ceho odrazit.
To je právě ono, že takováto dokumentace je po čase na nic. Pár refaktoringů (kolikrát jsem přejmenovával třídu, protože pod tíhou nových požadavků bylo její jméno nevyhovující) a vše je jinak.
Pokud to ovšem berete jako hrubou orientaci, pak ji máme. Používáme systém JIRA pro evidenci požadavků a máme jej provázaný s Fisheye (to je napojené na firemní subversion), takže u každého požadavku vidíme co se v projektu měnilo. Takže to je vlastně taky dokumentace a nároky na orientaci to splní jako vaše analýza a design.
Ja uz se tesim na ten pristi prispevek o review systemu - uz jsem parkrat premyslel jak neco takoveho efektivne a funkcne implementovat, ale zatim nemam uspokojive reseni.
BTW dik za typ na XMLmind, rozhodne se mu podivam na zoubek, uz je to davno kdy jsem se naposledy potkal s DocBookem a jeho zapis "WYSIWYG" editorem zni jako spravna cesta.
Okomentovat