Despre autodocumentare am aflat de la manualele IBM care prezentau modalităţi de scriere elegantă a programelor. Mai mult, am văzut cum IBM, care era în vremurile de demult ale informaticii, un etalon de performanţă, eleganţă şi eficienţă, avea scrise bibliotecile de subprograme, prezentate în manualul SSP.
Nu aş pleda pentru autodocumentarea programelor, dacă aceasta ar fi o şmecherie sau un moft.
Să ne imaginăm că am scris acum 5 sau 7 ani un program şi nu l-am autodocumentat. Să ne mai imaginăm că pe capul nostru cade măgăreaţa să facem mentenanţă, prin adăugarea unei secvenţe în care trebuie să mai facem oarece calcule, secvenţă care necesită:
- completarea listei de parametrii,
- definirea unor variabile de lucru noi,
- scrierea unor linii sursă de calcul,
- introducerea unor secvenţe de validare.
Cu siguranţă că vom bâjbâi să vedem semnificaţia elementelor din lista de parametrii. Cu siguranţă că vom pierde destul de mult timp până vom vedea ce variabile trebuie să definim şi unde vom insera liniile sursă pentru calculul indicatorului, dar şi unde vom insera liniile sursă pentru validare.
Când scriem programe ne gândim că nu noi vom fi cei ce vor face mentenanţă. de aceea nu ne prea interesează ce şi cum, mai ales că noi mergem pe principiul: după mine potopul.
Este moral şi normal să facem autodocumentare pentru că:
- există riscul ca de mentenanţă să ne ocupăm chiar noi şi aşa ne facem viaţa uşoară,
- programatorii vin şi pleacă din echipe şi dacă nu sunt autodocumentate programele, productivitatea celor ce se ocupă de mentenanţă va fi extrem de scăzută,
- chiar dacă un program este gândit din start să fie mentenabil, dacă nu este autodocumentat, este extrem de greu de a localiza punctele unde el trebuie completat,
- compararea care se face între programatori folosind texte sursă scrise de aceştia, este analizată şi prin stilul de programare utilizat, stil în care comentariile sunt esenţiale şi nu trebuie scrise oricum,
- programul autodocumentat este folosit şi la scrierea documentaţiei, căci dacă programatorul a dat dovadă de conştiinciozitate în autodocumentare, la elaborarea de documentaţii, va prelua comentariile din textul sursă şi le va concatena pur şi simplu, obţinând o mare parte de documentaţie a produsului.
Pledez pentru autodocumentare prin utilizarea unui şablon pornind de la cerinţele de realizare a documentaţiei. Programatorul va înşira variabilele şi în dreptul fiecăreia va scrie ceva despre tip, despre domeniu, despre validări, dar şi de valorile care rezultă. Acolo vor apare informaţii dacă variabila este de intrare, este rezultativă sau este utilizată pentru calcule intermediare.
Dacă autodocumentarea se face coerent, vor apare detalii legate de:
- data scrierii programului,
- mod de testare,
- algoritm utilizat,
- autorul programului,
- secvenţele de prelucrare,
- validările necesare,
- condiţionările de efectuare a calculelor,
- specificaţiile utilizate,
- compania unde s-a scris programul,
- resurse necesare,
- limitele problemelor de rezolvat,
- inecuaţii de definire a restricţiilor de dimensiune,
- ceva despre performanţe.
Dacă se construieşte un şablon, lucrurile vor merge foarte uşor. Dacă se vor scrie comentariile separate de textul instrucţiunilor folosind asteriscuri, lucrurile vor arăta şi mai interesant.
Ar fi bine ca la nivelul organizaţiei sau ale echipei de programatori să se definească nişte reguli şi tot poporul programatorilor să facă autodocumentarea în acelaşi fel, fără a lăsa găuri negre în textul sursă, căci costurile viitoare vor fi foarte mare, dacă aceleiaşi echipe sau organizaţii îi revine mentenanţa, ştiut fiind faptul că mentenanţa are costuri importante şi ea contribuie la eficienţa spectaculoasă a organizaţiei. Unii au vândut mii de locomotive de şantier la preţuri simbolice, dar costul pieselor de schimb era colosal, mai ales că la început, garanţia era cu gratuităţi. când au venit vremurile înlocuirilor, producătorul şi-a scos pârleala. Tot aşa şi la software. Vom vinde un produs la un preţ care să-l atragă pe beneficiar, dar mentenanţa va fi costisitoare. Beneficiarul nu o simte pentru că nu dă toţi banii grămadă, ci cu ţârâita. Este exact gândirea noastră care nu schimbăm un produs, ci preferăm să-l reparăm, deşi dacă adunăm banii cu reparaţiile ar fi rezultat cinci produse noi. Numai că am reparat în timp şi am plătit puţin câte puţin, dar tot s-au adunat şi era mai bine dacă rupeam pisica în două.
|
