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

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)

Několik "dobrých rad"

Proč je dokumentace potřeba

Triviální a při tom zavádějící odpovědí je "protože jinak byste nezískali potřebný zápočet".
To je sice "ve škole" pravda, ale "v životě" existuje i celá řada podstatnějších důvodů

Pro koho dokumentaci píšete

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.

Z čeho si nebrat příklad

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

Z čeho se dokumentace skládá a její struktura

To se může případ od případu velmi lišit.

S trochou zjednodušení můžeme říci, že do ní patří

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.

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.

Doprovodný dokument

V následujícím výčtu témat, které by dokumentace mohla obsahovat, nepředpokládáme její explicitní dělení na uživatelskou a programátorskou část (pro jednoduché úlohy to může být násilné, jindy naopak velmi přínosné).

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.

  1. Stručné zadání (anotace)
    Několik výstižných vět o tom, jakou úlohu Váš program řeší (a případně jak). Mělo by být čtivé, krátké a výstižné, nemusí být přesné.
    Hypoteticky by mohlo být uveřejněno v katalogu, aby dalo čtenáři informaci, zda se má o Váš program zajímat.
  2. Přesné zadání
    Je nutné napsat, pokud není možné napsat přesnou specifikaci úlohy stručně. Narozdíl od stručného zadání může (a mnohdy musí) být napsáno formálněji i s technickými detaily (popisujícími např. omezení na vstupní data).
  3. Zvolený algoritmus
    Popis algoritmu, který jsme zvolili. Není třeba psát, pokud je zcela zřejmý resp. zcela triviální.
    Pokud je algoritmus složitější a převzatý, stačí citace na (pokud možno všeobecně známou a dostupnou) literaturu. Jde-li však algoritmus popsat na méně než jedné straně textu je lepší ho explicite popsat.
  4. Diskuse výběru algoritmu
    Velmi často jste při výběru algoritmu uvažovali o více možnostech. Pokud tomu tak je, měli byste (stručně) charakterizovat zavrhnutá řešení a napsat důvody, proč jste si je nevybrali (při tom není nutné předstírat "vědecké" důvody). Tato část je velmi cenná pro někoho, kdo později bude dělat další verzi programu. I kdybyste to byli Vy, za několik let zapomenete důvody svých dnešních rozhodnutí.
    Pochopitelně nemůžete všechna alternativní řešení popsat stejně podrobně jako to, které jste se rozhodli realizovat.
  5. Program
    Zde by měly být popsány hlavní datové struktury používané v programu a jeho struktura - hlavní podprogramy a způsob jejich komunikace. Není nutné psát úplný výčet všech podprogramů (to často může dokumentaci velmi znepřehlednit).
  6. Alternativní programová řešení
  7. Obdobně jako u algoritmu jsme většinou uvažovali o více možnostech návrhu programu. Pro někoho, kdo by program měl v budoucnu modifikovat, může být velmi cenné vědět, o kterých řešeních jste uvažovali, a případně i proč jste je zavrhli.
Následující dvě části dokumentace je potřeba napsat pro
"absolutního idiota
, který navíc vůbec nechce spolupracovat".
Rozhodně nesmíte předpokládat znalost programování a hlubší porozumění problému.
Potenciálním čtenářem je (případně nedobrovolný) "uživatel programu".
  1. Reprezentace vstupních dat a jejich příprava
    Je potřeba explicitně do nejmenších detailů popsat i formát vstupních dat - např. vstupuje-li posloupnost čísel, zda musí být každé na nové řádce nebo na tom nezáleží.
  2. Reprezentace výstupních dat a jejich interpretace
    Výstupy dobře navrženého programu by měly být snadno pochopitelné - např. proto, že jsou do nich "opsána" vstupní data a "program odpovídá celou větou". Někdy to však (zejména kvůli rozsahu dat) nejde a pak je důležité, aby uživatel uměl (bez neúměrného úsilí) správně interpretovat obdržené výsledky

  3. Průběh prací
    Především u velkých programových děl může být zajímavé (mimo jiné i pro autora), jak vlastně práce na něm probíhala. Nemusíte mít strach, že by Vám upřímnost a pravdivost u učitele uškodila.

  4. Co nebylo doděláno
    Především u dobrých studentů se zájmem o programování se často stane, že si zvolí náročný cíl, se kterým nejsou do doby, kdy mají zápočtový program odevzdat, zcela hotovi.
    Pokud Váš program nedělá všechno, co jste původně plánovali (resp. naslibovali), neznamená to automaticky, že nemůžete zápočet získat. Nutnou (ale nikoli postačující) podmínkou k tomu je, aby bylo podrobně zdokumentováno všechno to, co hotovo není.
  5. Závěrečný povzdech
    "Kdyby sem to byl býval věděl, tak bysem sem nechodil" říkal kdysi malý chlapeček ve francouzském filmu Knoflíková válka. Subjektivní "belestristické" zhodnocení Vašeho poměru k právě dokončenému programu. Pro učitele to může být cenná zpětná vazba zda (a komu) příště podobnou zápočtovou úlohu zadat.

Sada testovacích příkladů

U mnoha úloh není jednoduché najít dostatečně malou sadu testovacích dat, která by skutečně prověřila správné chování programu programu ve všech typických i speciálních případech. Patří proto k "dobrému programátorskému stylu" navrhovat testovací data již při vzniku programu. Usnadní Vám to ladění a navíc je to v té době většinou snazší než v situaci, kdy je celý program "hotov" (a možná špatně).
V reálném životě od Vás nikdo programátorské dílo bez testovacích příkladů nepřevezme.
Je třeba si uvědomit, že testovací data musí být taková, abyste se byli schopni nějakou nezávislou (a pokud možnou nenáročnou) cestou přesvědčit o tom, jaké výsledky jsou skutečně správné.