Comentarii si Decalari

Comentarii si Decalari

Utilizarea judicioasa a comentariilor si utilizarea con­sistenta a decalarilor poate face sarcina citirii si intelegerii unui program mai placuta. Exista diferite stiluri ale decalari­lor. Autorul nu vede motive fundamentale pentru a prefera un stil fata de altul (deci, ca multi altii, eu am preferintele mele). Acelasi lucru se aplica si la 323c219d stilurile de comentare.

Comentariile pot fi omise, dar atunci citirea programului va fi serios afectata. Compilatorul nu intelege continutul unui comentariu, asa ca nu exista nici o cale de a ne asigura ca un comentariu:

[1] este de neinteles;

[2] descrie programul;

[3] este pus la zi.

Multe programe contin comentarii care sint incomprehensi­bile, ambigue si chiar eronate. Comentariile rele pot fi mai rele decit daca nu ar exista.

Daca ceva poate fi exprimat in limbajul insusi, ar trebui sa fie mentionat in el, nu numai intr-un comentariu. Aceasta remarca este intarita de comentariile de mai jos:

//variabila "v" trebuie sa fie initializata

//variabila "v" trebuie sa fie folosita numai de functia "f()"

//apeleaza functia "init()" inainte de a apela

//orice alta functie din acest fisier

//apeleaza functia "cleanup()" la sfirsitul programului

//sa nu se utilizeze functia "wierd()"

//functia "f()" are doua argumente

Astfel de comentarii pot adesea sa fie interpretate ca necesare printr-o utilizare corespunzatoare a lui C++. De exem­plu, s-ar putea utiliza regulile de linkere (&4.2) si vizibili­tate, initializare si curatire pentru clase (vezi &5.5.2) pentru a face exemplele precedente redondante.

Odata ce a fost afirmat ceva clar in limbaj, nu ar trebui mentionat a doua oara intr-un comentariu. De exemplu:

a = b+c // a devine b+c

count++ // se incrementeaza count

Astfel de comentarii sint mai rele decit redondanta: ele maresc cantitatea de text pe care trebuie sa o citeasca programa­torul si ele adesea fac mai obscura structura programatorului.

Preferintele autorului sint pentru:

[1] Un comentariu pentru fiecare fisier sursa care sa afirme ce declaratii din el se utilizeaza in comun, scopuri generale pentru mentinere, etc.

[2] Un comentariu pentru fiecare functie netriviala care sa indice scopul ei, algoritmul utilizat (daca nu este evident) si poate ceva despre mediul de executie al ei.

[3] Citeva comentarii in locurile unde codul nu este evident si/sau neportabil.

[4] Foarte mici alternative else.

De exemplu:

// tbl.c: Implementarea tabelei de simboluri

/* Eliminare Gauss prin pivotare

partiala. Vezi Ralston:...pg...

*/

//swap() presupune utilizarea stivei la un AT&T 3B20.

/ ** ** ** ** *****

Copyright (c) 1984 AT&T. Inc.

All rights reserved

** ** ** ** *****/

Un set de comentarii bine ales si bine scris este o parte esentiala a unui program bun. Scrierea de comentarii bune poate fi tot atit de dificil ca si scrierea programului insusi.

Sa observam, de asemenea, ca daca se folosesc comentariile cu // intr-o functie, atunci orice parte a acelei functii poate fi comentata utilizind stilul de comentarii /*...*/ si viceversa.