Jak psát dokumentaci zápočtového programu

Specifika dokumentace zápočtového programu
(v prvních letech studia)

• Pokud váháte nad rozsahem dokumentace, přikloňte se k delší variantě. Přirozená lenost Vás pak časem dovede k jejímu rozumnému rozsahu. V opačném případě se lenost nestane Vaším spojencem, ale protivníkem, který bude kazit výsledky Vaší práce.
• Pokud máte pocit, že píšete blbosti jen proto, abyste udělali radost učiteli, který Vám bude dávat zápočet, nedělejte to. Jistě mu tím radost neuděláte.
  Raději zajděte (po tom, co jste o tom dostatečně dlouho přemýšleli) na konzultaci a učitel Vám rád pomůže s rozlišením toho, co skutečně blbosti jsou a co se jimi stalo, protože to neumíte dobře napsat.
• Dokumentace je konec konců svého druhu literární žánr. Nespokojujte se proto s její "první verzí", ale čtěte ji po sobě a vyhrajte si s formulacemi. Jako v každém jiném kulturním textu by i v dokumentaci každá gramatická věta měla buď nést nějakou myšlenku nebo by z kontextu mělo být okamžitě jasné, že v ní má nějakou jinou roli (třeba pohladit čtenáře).

• Pokud nespecifikujeme, co má program dělat, nemá vůbec cenu klást si otázku, zda to program skutečně dělá.
  Jediné co pak autorovi i uživatelům zbývá je náročná experimentální práce s programem ve snaze zjistit co by tak možná mohl dělat. Ta může být (a zpravidla i je) podstatně obtížnější než vlastní napsání programu. O to víc vynikne zbytečnost takového úsilí.
• Abychom vůbec zvládli vytvořit větší programové dílo.
• Abychom byli schopni modifikovat cizí (ale i vlastní po delší době) program, bez nebezpečí vzniku těžko odstranitelných chyb.
• Aby na programu mohlo spolupracovat více programátorů.

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.
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.

Bohužel z většiny manuálů (zejména velkých) výrobců komerčího software.
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.

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,
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 }

to je jistě cenná informace

X:=X+1;    { Přičtení jedničky k proměnné X }

kdo si myslí, že tohle může někomu v něčem pomoci, tomu není pomoci.

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);

pak komentář

{ Otočení začátku pole }

mnoho nepomůže,
Daleko cennější je např. komentář

{ Do začátku pole B - až po index N - se zkopíruje } { otočený začátek pole A délky N. } { Hodnoty zbytku pole B se nezmění. }

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.

Sada testovacích příkladů