Dokumentace kodu

[Josef Štengl]

Jen doplním.
Od verze 1.8.8 umí doxygen přímo generovat obrázky přímo z programu DIA (mimo graphviz, jak už někdo zmínil). Trochu to 
kazí fakt, že dia se už nějak moc nevyvíjí, ale což, používám i jiné prográmky na které se 10 let nesahlo a slouží :-)

Pro psaní lze s výhodou použít rozšířené markdown syntaxe (jak v komentářích, hlavně tabulky), ale hlavně v samostatných 
souborech - (stránky popisující o čem to je a kde začít).

Pro (nejen) realtime systémy nepoužívat UML (je určen pro objektově orientované návrhy) ale podívat např na SDL-RT. Když 
se rozhodnete, že z toho nechcete generovat kód, lze používat takovou uvolněnou syntaxi,  člověk to pochopí a stroji je to 
jedno. Dobře se v tom navrhuje a kódování je pak už jen rutinní činnost (bohužel :-).

Doxygen má dost omezené možnosti, ale tak nějak časem jsem to začal brát jako výhodu. člověk se moc nerozvášní, zůstává u 
důležitého a snadno se hledají známé vzory. Podle mě je to čitelné a člověka to donutí psát k funkcím i trochu 
pochopitelnou dokumentaci :-)

Já tak píši (doxygen) uživatelskou dokumentaci k modulům. Generuji ji pouze z H souborů (podle mě v C souborech 
dokumentace jen překáží - co má funkce dělat je v H (jinak je stejně ten sobor takový ... prázný) a v C jsou jen 
implementační poznámky, které uživatele stejnak nezajímají (zejména u knihoven). No ale chce to pracovat jak C tak H 
soubory zároveň, což někteří lidé snášejí ... ne moc dobře.

Začínám psát vždy první H soubor abych si rozmyslel, to vlastně má umět.

\note
No což, jak tak koukám, TI zabstakňuje i HW, to je samé unified u názvu periférie ... Du rozběhat hodiny, ten hodinkový 
tick je sice sympatický, ale nějak to nepočítá :-)

ced

Dne 18.6.2015 v 13:34 mrazik napsal(a):
> 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
>
> _______________________________________________
> HW-list mailing list  -  sponsored by www.HW.cz
> Hw-list na list.hw.cz
> http://list.hw.cz/mailman/listinfo/hw-list
>