verze 1.01 z 27.listopadu 2002
Rudolf KRYL
Tento text má pomoci těm, kteří nemají jasno v tom,
co má být součástí dokumentace zápočtového programu,
a dát námět k přemýšlení těm, kdo o tom jasno mají.
Nutně je subjektivní a v žádném případě si neosobuje právo něco někomu předepisovat.
Specifika dokumentace zápočtového programu
(v prvních letech studia)
Opět nám triviální odpověď, že pro toho, po kom chcete zápočet, moc nepomůže.
Zajímavější je otázka, jaké vědomosti můžete u čtenáře dokumentace očekávat. Bohužel z většiny manuálů (zejména velkých) výrobců komerčího software. Užijte si toho, že na universitě Vás
ještě nikdo do podobně pokleslé produkce nenutí.
S trochou zjednodušení můžeme říci, že do ní patří
Jedinou vyjímkou, je doporučení,
aby prvních několik řádek programu obsahovalo
identifikaci programu,
Doporučuji, abyste dokumentaci psali pro své chytré kolegy, kteří však nic nevědí o úloze,
kterou řešíte.
To platí obecně - až na ty části, které popisují, jak se program spouští,
jak se pro něj připravují vstupní data a jak se interpretují výstupy programu.
Ty musíte psát pro absolutního hlupce, který navíc nemá ani dobrou vůli něco chápat.
Z čeho si nebrat příklad
Ty se většinou svým slohem a informační hodnotou podobají nejpíše reklamám na prací
prášky či vložky. To sice umožňuje velmi dobré bydlo
vydavatelům nejrůznějších "populárně odborných" časopisů
a autorů knih s obsahem "co by mělo být - ale není - v dokumentaci"
(jsou to mnohdy přímo autoři těch špatných dokumentací),
ale současně to výrazně přispívá
k "informačnímu smogu" našeho (postmoderního) světa.
Z čeho se dokumentace skládá a její struktura
To se může případ od případu velmi lišit.
Mají pochopitelně význam jen u interaktivních programů.
Mohou do značné míry nahradit
doprovodný dokument. Rozhodně však ne přesné zadání úlohy a pokyny k přípravě dat.
O tyto části se může zajímat i někdo, kdo váš program - zatím -
vůbec spouštět nechce
(představte si, že byste v autoškole mohli dostat informaci o tom, k čemu je volant a brzda,
jen po té, co by se už auto rozjelo).
Ta shrnuje informace potřebné pro práci s programem.
Ta shrnuje informace o algoritmickém řešení, struktuře programu,
podprogramech a datových strukturách,
o tom, jak by se měl modifikovat při té které předpokládané změně zadání atp. .
Komentáře ve zdrojovém textu programu
Opět nebudeme dávat přesné návody, omezíme se jen na několik hlavních zásad.
t.j. informace o úloze,
kterou program řeší, o autorovi, o roku vzniku programu,
o zápočtu, který za program chcete získat a pod.
Např. v Pascalu mohou tyto řádky vypadat:
{ Piškvorky } | |
{ Josef Hnipírdo, I. ročník, 118. st. skupina } | |
{ zimní semestr 2002/3 } | |
{ Programování PRM001 } |
U všech podstatných proměnných a typů by měl být vysvětlen jejich význam.
Druhou nejdůležitější zásadou pro psaní komentářů v programu je, že by měly obsahovat informaci co a proč se v daném úseku programu dělá a nikoli jak se to dělá. Triviální příklad:
PocetAut:=PocetAut+1;
{ Koupě dalšího auta }
|
X:=X+1;
{ Přičtení jedničky k proměnné X }
|
Dobrým zvykem je také, aby u každé hlavičky podprogramu bylo napsáno,
co podprogram má dělat. Je nutné to vyjádřit "v řeči formálních parametrů".
Opět jednoduchý příklad:
Máme-li v programu proceduru (nezabýváme se teď vhodností jejího návrhu,
ale způsobem komentování),
procedure zpracuj(A:pole; N:index; var B:pole);
|
{ Otočení začátku pole }
|
{ Do začátku pole B - až po index N - se zkopíruje }
|
Někdy může být vhodné uvést i příklady volání podprogramu. Např. v Prologu je to zcela běžné.
Rozhodně nějak označte komentářem v programu ta místa, na něž jste hrdí, jak jste to tam šikovně udělali. Z vlastní zkušenosti vím, že se případné zákeřné chyby vyplatí začít hledat právě tam.
Je jasné, že mnohé z těchto bodů mohou v dokumentaci pro konkrétní program chybět a případně jiné přibýt.
Berte proto tento výčet jako inspiraci, ne jako předpis.