Pisanje dokumentacije

Zanima me, kako drugi pišete razvojno dokumentacijo.

Sam sem skozi programersko kariero večkrat spremenil stil pisanja programov. Kot začetniku mi je bilo pomembno, da program dela in je čim prej končan, ne pa, kako je napisan. Potem sem začel pisati komentarje in ustrezno poimenovati spremenljivke, funkcije, razrede itd. Sedaj, ko se srečujem z težko razumljivimi algoritmi, sem se navadil pisati razvojno dokumentacijo. Težava je, ker je meni kot avtorju programa vse jasno (če ne, malo prelistam program in takoj vidim kaj sem mislil) in se težko odločam kaj sploh pisati. Nič posebnega, saj vsi programerji začnejo približno enako.

Trenutno se držim mnenja, da je pomembno kaj funkcija naredi, ne pa kako to naredi. Tudi ko iščem določene stvari po spletu (copy-paste), se ne sekiram kako je določena stvar narejena (razen če gre za varnost), da le dela, kot je treba. Med programiranjem si v word sproti izpisujem funkcije (tip funkcije, ime funkcije, tip parametrov, imena parametrov) in za vsako razložim kaj vrne v katerem primeru. Če je težko razložiti v enem stavku, postopek nakažem še s primerom. Če uporabljam več razredov ali knjižnic razložim še strukturo, tako da je lažje sklepati kaj se v razredu nahaja in kje iskati katero funkcijo.

Takšen je moj način pisanja dokumentacije (zaenkrat ni bilo pripomb). Kako pa ostali pišete razvojno dokumentacijo? Mogoče bom ob branju dobil še kakšno idejo.

Jaz osebno se držim slednjega:

-> Language conventions
--> Framework conventions
-> Dolgi komentar z opisom pred metodo
--> Minimalni komentarji v metodam

Recimo za prvi dve točki kadar programiram za splet PHP: PHP Convention se držim pravil, ki se jih drži največja skupnost okoli jezika nato pa tisto česar se drži skupnost frameworka recimo Laravel. Držiš se skupnega načina identacije, prepolavljanja vrstic, dolžine vrstic, kaj in kje komentirati, način poimenovanja metod in spremenljivk (camelcase, uppercase) itd..

Pred metodo, dam vedno multi line komentar. Konkretno opišem kaj metoda počne v sami metodi pa se držim minimalnih komentarjev kajti če se držiš skupno sprejetega standarda bi mogla sam koda biti enostavna za prebrat in razumet. V glavni komentar dodam tage:
@params, @return, @route..

Na koncu imam svoj parser imaš na voljo tudi public software, ki mu podam root svojega projekta slednji se sprehodi po vseh datotekah vsak kontroller, model, view, helper, primerja oo patterne in sproti gradi PDF dokument kjer so vse metode in kontrolerji opisani.

Tako, da na koncu imam zelo lepo sestavljeno PDF dokumentacijo skupaj z opisom strukture, datotek, metod bla bla bla. In za kazalom vse kar ostane je da v Photoshopu popravim in dodam par strani ročno recimo opis kako se vse komponente združijo v celoten app.

Tip. Ena stvar, ki jo sam počnem, da ugotavljam kako dober sem. Vsake pol leta vzamem en source in dokumentacijo enega projekta, ki je 6 mesecev ali več star in probam nekaj spremeniti na tak način na hiter vidim kako lahko je bilo zadevo urediti in to mi pove kako dobro komentiram kodo in sestavljam dokumentacijo.

Ko enkrat nimaš problema spreminjati 2-3 leta star projekt potem veš, da nekaj počneš prav. Ob tem pa tud ugotoviš kje si včasih preveč kompliciral .