|
Prin autodocumentare se înţelege scrierea de comentarii în program, care au rolul de a-l ajuta pe programator să depaneze peste ani şi ani un program, permiţându-i să înţeleafă:
- semnificaţia variabilelor,
- rolul funcţiilor definite,
- delimitarea secvenţelor omogene,
- care au fost sursele,
- detalii despre codurile utilizate în selecţii,
- algoritmii utilizaţi,
- restricţiile de apelare a funcţiilor din biblioteci,
- limite de dimensionare a datelor definite static,
- şi multe, multe altele.
Comentariile trebuie să fie:
- riguroase,
- scurte,
- puternice,
- convingătoare,
- independente,
- clare,
- fără redundanţă,
- sistematic plasate,
- predictibile,
- aşteptate,
- suficiente,
- complete,
- ordonate.
De regulă, programatorii urmăresc să realizeze programe, care conduc la rezultate corecte în urma testărilor, amânând pentru mai târziu scrierea comentriilor, ca în final să uite de comentarii şi să livreze programele neautodocumentate. Dacă mentenanţa o va realiza altcineva, este o situţie favorabilă, dar dacă mentenanţa o va realiza peste ani şi ani cel care a scris programul cândva, dar între timp a scris zeci sau sute de alte programe, acestuia îi va fi foarte greu să facă depanare şi absenţa comentariilor se va răzbuna pe lungirea extrem de mare a duratei procesului de mentenanţă, cu costuri foarte mici totuşi, căci toată lumea va presupune că programul a fost autodocumentat.
|
|
#
#
# Programul exemplifică folosirea comentariilor pentru a realiza
# o bună autodocumentare pentru procesul de mentenanta
#
#
# *************Functia de adunare a doua numere
def adunare(a,b):
return (a+b)
#
# *************Functia de scadere a doua numere
#
def scadere(a,b):
return (a-b)
#
# *************Functia de inmultire a doua numere
#
def inmultire(a,b):
return (a*b)
#
# *************Functia de impartire a doua numere
#
def impartire(a,b):
return (a/b)
A = 3 # prima latura a triunghiului
B = 4 # a doua latura a triunghiului
C = 5 # a treia latura a triunghiului
P = adunare(A,B)
P = adunare(P,C) # calculul perimetrului P al triunghiului
S = inmultire(A,B)
S = impartire(S,2) # calculul ariei S a triunghiului
# ******************Afisarea rezultatelor
print('Latura este', A)
print('Latura este', B)
print('Latura este', C)
print('Perimetrul triunghiului este', P)
print('Aria triunghiului este', S)
|
|