tag:blogger.com,1999:blog-8478588303162378135.post1885823360681996580..comments2018-12-01T01:06:55.293+01:00Comments on jirablog: jOpenSpace 2008 - Dokumentace - nezatracujme FOPJirahttp://www.blogger.com/profile/08468747543558661137noreply@blogger.comBlogger9125tag:blogger.com,1999:blog-8478588303162378135.post-27565819709116082872008-10-17T22:26:00.000+02:002008-10-17T22:26:00.000+02:00Ja uz se tesim na ten pristi prispevek o review sy...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.<BR/><BR/>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.Srakyihttps://www.blogger.com/profile/09905814978268245923noreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-15885082075846489532008-10-16T12:02:00.000+02:002008-10-16T12:02:00.000+02:00To je právě ono, že takováto dokumentace je po čas...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.<BR/><BR/>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.Jirahttps://www.blogger.com/profile/08468747543558661137noreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-12655590298974474832008-10-16T11:02:00.000+02:002008-10-16T11:02:00.000+02:00Ja nesouhlasim - naopak si myslim, ze bez dokument...Ja nesouhlasim - naopak si myslim, ze bez dokumentace snad ani neni mozne velky software psat.<BR/><BR/>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.<BR/><BR/>Samozrejme je problem, ze ty designy a analyzy postupem casu starnou a nereflektuji skutecnost.<BR/><BR/>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.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-67344587859139987252008-10-14T15:01:00.000+02:002008-10-14T15:01:00.000+02:00Právě jsem našel následující http://java.dzone.com...Právě jsem našel následující <A HREF="http://java.dzone.com/articles/reverse-engineer-source-code-u" REL="nofollow">http://java.dzone.com/articles/reverse-engineer-source-code-u</A> a vypadá to hodně slibně, vyzkouším ...Jirahttps://www.blogger.com/profile/08468747543558661137noreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-54902415984728248572008-10-14T08:09:00.000+02:002008-10-14T08:09:00.000+02:00No, pokud mate takove pokryti testy, ktere jsou kv...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.Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-43990102442935740072008-10-14T07:47:00.000+02:002008-10-14T07:47:00.000+02:00Plně si uvědomuji, že kód v podstatě nemáme dokume...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.<BR/><BR/>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).Jirahttps://www.blogger.com/profile/08468747543558661137noreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-19379350414341978632008-10-14T07:42:00.000+02:002008-10-14T07:42:00.000+02:00To honza novotný: Z DocBooku jsme si vybrali podmn...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.<BR/><BR/>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.<BR/><BR/>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.<BR/><BR/>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 ...Jirahttps://www.blogger.com/profile/08468747543558661137noreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-18949025080529879672008-10-14T07:26:00.000+02:002008-10-14T07:26:00.000+02:00No tak s tim o psani dokumentace do kodu moc nesou...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.<BR/><BR/>Ani ten nejprehlednejsi kod v tom nepomuze, kdyz zakaznik (a to je zcela bezne) upravuje sve pozadavky a do mnohdy obskurdnich smeru.<BR/><BR/>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.<BR/><BR/>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)Anonymousnoreply@blogger.comtag:blogger.com,1999:blog-8478588303162378135.post-76800217103646108622008-10-13T17:56:00.000+02:002008-10-13T17:56:00.000+02:00S tímhle názorem více méně souhlasím a defakto to ...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. <BR/><BR/>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.<BR/><BR/>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.<BR/><BR/>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.<BR/><BR/>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.<BR/><BR/>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á.Anonymousnoreply@blogger.com