Dokumentiranje programov


Dokumentiranje programov je prav tako pomembno, kot je pomembno, da pri nakupu novega izdelka dobimo zraven tudi navodila za uporabo.
 
Pri dokumentiranju programov moramo pomisliti na to, komu so namenjena:
 
Uporabniku programa (on potrebuje navodila za uporabo)
Programerju (on potrebuje opis sistema)

 

Navodila za uporabo so lahko tudi integrirana v sam program v obliki takoimenovane pomoči.
 
Pod programerjem pa razumemo tistega, ki bo morda kasneje program vzdrževal in odpravljal napake in pomanjkljivosti. Morda ga bo tudi predeloval, izpopolnjeval in razširjal.
 
Pomislimo na to, kakšno dokumentacijo programa bi si želeli, če bi bili mi tisti, ki bi morali predelovati program nekoga drugega!!
Ne zanašajmo se, da je program sam po sebi dovolj jasno napisan, da ga bomo po kakšnem letu sami še vedno povsem razumeli (ker bomo razočarani in nam bo žal)!!
 
Najmanj, kar moramo storiti, je to, da program opremimo z dovolj zgovornim komentarjem. Posebej moramo dokumentirati (ali vsaj opisati s komentarjem) naslednje:

 

Pri funkcijah moramo tudi podati pomen vhodnih parametrov in pomen izhoda, ki ga taka funkcija tvori ali vrača.

V nekaterih programskih okoljih, kot je na primer Java, imamo tudi možnost avtomatske tvorbe dokumentacije. Pri Javi na primer moramo pred vsako funkcijo pomen te funkcije in njene parametre podati s posebno obliko komentarja, ki ga poseben program nato predela v dokumentacijo.

 

Pri bolj obsežnih programih samo komentar ne zadošča. Izdelati moramo tudi »Opis sistema«, v katerem podamo strukturo programa, sestavljenega iz posameznih programskih modulov, pomen posameznih modulov, po možnosti tudi bistvo nekaterih pomembnejših algoritmov.

K dobri dokumentaciji sodi tudi to, da na začetku navedemo avtorstvo in verzijo programa. Temu naj bi sledila še navedba kronoloških sprememb, ki so bile uvedene v program.