10 komentáře “Zamyšlení nad tvorbou programátorské dokumentace

  1. Zpětný odkaz: » Nástroje pro vývoj web aplikací ve Forrestu Myšlenky dne otce Fura

  2. @v6ak Tohle je pro nás no-brainer – vzhledem k tomu, že hlavní naší devizou je naše CMS: http://www.edee-cms.cz/ , tak je pro nás nejlevnější a nejproduktivnější nasadit na tenhle úkol náš vlastní diskusní modul (to by nám nemělo zabrat víc jak pár hodin).

  3. „V tomto centrálním místě by mělo být možné nad libovolnou kapitolou diskutovat“
    Dobrá poznámka. Máte nějaké tipy na nástroje pro tuto diskuzi?

  4. Dík za přínosný článek, umím si představit tu plnou hlavu po takovém brainstormingu 🙂 Ještě bych k tomu dodal:
    – “nejlepší dokumentace je zdrojový kód … – jenže je to omyl.“ – on to není ani tak omyl, spíš neúplná pravda. Tuhle větu slýchám často v souvislosti s důrazem na správné pojmenování a v tomto smyslu se s ní ztotožňuji, nicméně souhlasím, že není důvodem nedělat ostatní typy dokumentace, o kterých jste psal. Jinak než se dostat do stavu: /** @return false */ boolean foo() {return true;} – to radši nic.
    – překážkou psaní javadocu je také nutnost psát v HTML. Podpora v Eclipse pro doplňování tagů není ideální. Často používané prvky jsou ul,ol,li a bylo by mnohem pohodlnější, kdyby javadoc akceptoval nějaký wiki formát přímo. Tím by bylo vyřešeno i „aby vás to nelákalo, hrát si s formátováním“
    – „Navíc jsem si potřeboval utřídit myšlenky a psaní mi v tom pomáhá“ – tohle se dá aplikovat i na samotné psaní dokumentace. Taky nedokumentuju neusazené API, ale zároveň jsem se odnaučil dívat se na nedokumentované API pohledem ‚už tomu chybí jen ta dokumentace‘ – potřebu refactoringu často objevím až při psaní dokumentace.

    • @Tomáš Záluský:
      – nejlepší dokumentace je kód: v tomhle směru jsem se spíš snažil oslovit ty, kteří se touto větou ohánějí jako výmluvou proč dokumentaci nepsat. Nechci zpochybňovat to, ze i přes nejdokonalejší dokumentaci se do kódu někdy musí a proto by měl podle toho vypadat.
      – formátování: formátování je zlo – souhlasím, ze nějaký Wiki nebo APT by mohl být lepší (jenže třeba takový zápis tabulky v Apt je taky velmi ošklivá záležitost), důležitá je ale jen změna mindsetu – když dokumentuji, soustředím se na obsah a ne na formu
      – dokumentace hotového API: na tohle mi reagoval jeden kolega z firmy úplně stejně a něco pravdy na tom určitě je. Odpovídal jsem mu, ze já obvykle nejsem schopný nastřelit API napoprvé správně a ještě nějakou dobu si s ním hraji a masivně refaktoruji. Při tomhle stylu vývoje je myslím lepší posunout dokumentaci až ke konci realizace – tam je ještě možné API začistit podle toho, co mě napadne při psaní dokumentace, ale už vím ze to budou více méně jen kosmetické změny.

  5. @David Skýba: Kathy Sierru mám taky rád: http://blog.novoj.net/2008/05/21/vasnivi-uzivatele/ … problém pro mě je překlenout tu propast mezitím, co bych chtěl a co jsem aktuálně schopen 😉

    @Jakub Vrána: chtěl bych to řešit tak, že primárně by měl vývojář používat referenční dokumentaci k té verzi, kterou má na své instalaci (taktéž i slohovou). Samozřejmě by někde stranou existovala refereční a slohová dokumentace i pro nejaktuálnější verzi, kam by bylo možné kdykoliv nahlédnout. Připadá mi to přehlednější a jednodušší způsob než časté anotace @since a @deprecated v dokumentačním textu.

    Díky všem za postřehy. Jsou pro mě velmi cenné.

  6. Souhlasím s katastrofálním stavem dokumentace ke Groovy i s tím, že dokumentace ke Springu je na skvělé úrovni. Tedy od verze 2, v 1.2 to byl taky dost děs. Ale Groovy už patří pod SpringSource dost dlouho na to, aby s tím chlapci něco udělali 🙂

    Já se momentálně potýkám s naprosto nevyhovující strukturou dokumentace, kvůli které musím lidem vysvětlovat spoustu věcí, které by si bývalo stačilo přečíst. Takže díky za motivující článek.

  7. Sqelý článek.
    Praxe v .NET je však ve spousta firmách tragická. Dokumentaci negenerujeme a kvalitní API také neumíme napsat, o to je to horší bez dokumentace.
    Přitom ja mám takový narcistický sklon si procházet vygenerovanou dokumentaci a koukat se jestli je to API dost hezký, intuitivní a popsané. Bohužel tyto mé choutky jsou neukojeny a velký podíl na tom má i Microsoft, že dlouho nebyl dostupný ekvivalentní nástroj k JAVADOCU.

    A přitom je to přesně jak říkáš, kdo umí dokumentovat, tak umí i dobře psát kod.

  8. Výborný přehled. Také se kloním k tomu dokumentovat co nejblíž kódu. A ne někde bokem ve Wiki jako to má třeba Nette (a chtělo by se dodat – taky to podle toho vypadá).

    S verzováním dokumentace to ale záleží na projektu. Např. v oficiálním manuálu PHP jsme taky zvažovali, že dokumentaci rozdělíme podle verze PHP, tam by to ale bylo kontraproduktivní, protože jako programátor často potřebuji vědět, v kterých všech verzích mi kód bude fungovat. A i když bych třeba věděl, že mi projekt poběží na jedné konkrétní verzi PHP, tak ho stejně chci psát tak, aby byl dopředně kompatibilní.