Dokumentace kodu

[Galloth]

Podle mne tato veta hodne vypovida o tom, jake programy jeji autor pise.
Pokud pise program, ktery otevre soubor A, cisla v nem oddelena strednikem
zobrazi do tabulky a pak je zase ulozi do podobneho souboru, tak si urcite
dokaze vystacit s vhodne a vystizne pojmenovanymi promenymi a funkcemi.
Ostatne takovych ukolu je spousta. Znam nekolik firem delajicich GUI
jejichz programatori tvrdi, ze pokud se pise komentar, tak jsou spatne
zvolene nazvy promenych.

Pokud ale program ma resit algoritmicky slozitejsi ulohu, popripade pokud
ji ma  resit hodne efektivne, tak se proste bez komentaru neobejdete. Uz
jsem zazil i situaci, kdy nam trvalo skoro tyden, nez jsme dokazali, ze
funkce dela to, co delat ma. A to proto, ze z duvodu optimalizace jeji
autor provedl s vypocitavanym vzorcem nekolik uprav, ktere samozrejme nikde
nezdokumentoval. Takze ve vysledku jsme meli jeden vzorecek, ktery rikal,
co se ma pocitat, pak vzorecek co se pocital a pak dukaz, ze tyto vzorecky
jsou ekvivaletni. A tohle uz bez dokumentace neokecate.

Honza

Dne 18. června 2015 18:52 Michal Gregor <a2x1nptda8 na email.cz> napsal(a):

> No v jedne knizce se pise:
> "Dobre napsany kod nepotrebuje komentare."
>
> Michal Gregor
>
> Dne 18.6.2015 v 11:57 Karel M napsal(a):
>
>> 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. 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.
>>
>> Dne 18. června 2015 10:58 Jan Waclawek <konfera na efton.sk
>> <mailto:konfera na efton.sk>> napsal(a):
>>
>>     Pozrite http://www.efton.sk/misc/snake.zip (robi to toto:
>>     https://www.youtube.com/watch?v=pCx6SKWVDkw)
>>
>>     Vyznate sa v tom? Tak to berte ako kladny priklad. Ak nie, berte to
>> ako
>>     zaporny priklad.
>>
>>     wek
>>
>>
>>     PS. zrejme Vam doporucia doxygen - ja osobne to mam rovnako nerad ako
>>     arduino ;-)
>>
>>
>>
>>     ----- Original Message ---------------
>>
>>      >Pěkný den, rád bych provedl dokumentaci programu psaného v C
>>     určeného pro
>>      >MCU AVR, tak aby to snadno mohl převzít jiný programátor, nebo i
>>     já sám
>>      >když bych se po čase k programu vrátil. Bohužel s tím nemám žádné
>>      >zkušenosti, chtěl bych Vás poprosit, zda nemáte nějaký naučný
>> příklad.
>>      >Díky
>>      >Karel M.
>>
>>     _______________________________________________
>>     HW-list mailing list  -  sponsored by www.HW.cz <http://www.HW.cz>
>>     Hw-list na list.hw.cz <mailto:Hw-list na list.hw.cz>
>>     http://list.hw.cz/mailman/listinfo/hw-list
>>
>>
>>
>>
>> _______________________________________________
>> HW-list mailing list  -  sponsored by www.HW.cz
>> Hw-list na list.hw.cz
>> http://list.hw.cz/mailman/listinfo/hw-list
>>
>>  _______________________________________________
> HW-list mailing list  -  sponsored by www.HW.cz
> Hw-list na list.hw.cz
> http://list.hw.cz/mailman/listinfo/hw-list
>
------------- další část ---------------
HTML příloha byla odstraněna...
URL: <http://list.hw.cz/pipermail/hw-list/attachments/20150618/800c3ecc/attachment.html>