Dokumentace kodu

[mrazik]

Doxygen je jen nástroj, lze ho použít různě. Dále v textu

On 06/18/2015 11:57 AM, Karel M wrote:
> Ano, vyznal bych se v tom, ale měl jsem na mysli něco jako souhrnný
> dokument, obsahující např. jaké funkce mám k dispozici, jaké procesy
> se dějí v přerušení od timerů, prostě celkový náhled na složitý
> projekt násobně větší než ten snake game.
To není problém, jen to musíte prostě napsat. Samo se to neudělá. Dobré
je dodat nějaké obrázky a grafy. Dá se to udělat pomocí graphviz, ale to
se zase musíte naučit. Ty grafy závislostí, co se generují automaticky,
jsou naprosto nepřehledné, neumějí samy rozpoznat podstatné.
> Doxygen mi přijde jako zanášející bordel do kodu a dělá jej tak
> nepřehledným. Bloková schémata zas příliš jednoduchá nepopisující
> souvislosti. Nejde o to popsat každý řádek funkce, spíš něco co když
> přečtu tak získám obecný přehled co se tam děje.
> K.
>
Doxygen v kódu nemá co dělat. Všechno je to lepší dát do hlaviček,
případně do samostatného souboru.

Jestli najdete nějaký systém, který prohlédne kód a sám z něj udělá
nějaký přehledný výcuc, dejte vědět, taky by se mi to hodilo. Ale obávám
se, že umělá inteligence tak daleko ještě není. Staří bardové říkají, že
nejlepší dokumentace je kód sám, tedy je dobré ho psát tak, aby byl
srozumitelný. Opak je prý příznakem špatného návrhu. Já sám to neberu
příliš vážně, ono když něco začínáte psát, tak většinou nevíte ještě
přesně jak to bude (a jestli vůbec) fungovat, a když už to rozchodíte a
víte jak by to vypadat mělo, nechce se vám to přepisovat tak, aby tomu
ještě ke všemu bylo rozumět. A většinou na to ani není čas.

Mrazík