În ultimele două numere ale TSM am descoperit ce fel de denumiri ar trebui să utilizăm pentru metodele, câmpurile, clasele noastre și așa mai departe. În legătură cu aceasta, am văzut că ar trebui întotdeauna să utilizăm nume cu înțeles care au legătură cu problema pe care dorim să o rezolvăm. De asemenea, am văzut că un nume de metodă trebuie întotdeauna să exprime o acțiune - să înceapă cu un verb- iar un nume de clasă ar trebui să fie întotdeauna un substantiv. După aceasta, am vorbit despre funcții, când am aflat că o funcție ar trebui să fie scurtă, să facă numai un singur lucru, iar numărul parametrilor să fie limitat.
Toate informațiile din această serie sunt inspirate din "Clean Code", scrisă de Robert C. Martin. Sper ca în acest fel să reușesc să conving oamenii să citească această carte și să scrie un cod mai bun.
În acest articol vom vorbi despre comentariile din codul nostru și despre formatul codului. Scopul nostru este de a încerca să aflăm când anume ar trebui să adăugăm comentarii în codul nostru și cum ar trebui să arate aceste comentarii. Deoarece dezvoltatorii trebuie să citească cod în fiecare zi, trebuie să folosim un stil de editare bun, care să ajute dezvoltatorii să citească codul cât mai ușor posibil. Să deschidem seria comentariilor.
Când ne gândim la comentarii în cod, avem în minte comentarii care explică ce face codul. Problema cu aceste comentarii este că ele nu sunt actualizate întotdeauna. Foarte des codul este schimbat, dar vechile comentarii rămân aceleași. Deci comentariile nu mai reflectă codul.
Cu timpul, codul este mutat dintr-o locație în alta, este restructurat, divizat și mutat. Chiar dacă locația codului s-a modificat, vechile comentarii rămân în aceeași locație. După o vreme, ajungem să avem comentarii care nu reflectă realitatea sau codul din jurul lor.
Cel mai dificil lucru este să educi dezvoltatorii și să îi faci să înțeleagă că comentariile fac parte din cod. și, în momentul în care codul este modificat, același lucru trebuie să se întâmple și cu comentariile. Dar din cauza lipsei de timp sau a indiferenței, sfârșim prin a avea comentarii învechite, care nu mai reflectă realitatea.
Trebuie să ne gândim la comentarii ca și la documentație. Este un artefact scump care trebuie întreținut. Din această cauză, ar trebui să adăugăm comentarii numai în acele locații unde este necesar și codul în sine nu poate exprima ceea ce se întâmplă acolo.
Adesea, comentariile sunt utilizate acolo unde codul este greșit și sunt folosite pentru a "repara" codul. Nu încercați să înfrumusețați codul prin adăugarea de comentarii. Atunci când aveți un cod urât ar trebui să îl restructurați și să îl rescrieți într-un fel care să exprime ceea ce faceți acolo.
Atunci când aveți un cod care nu poate fi înțeles, comentariile nu sunt soluția. Încercați să rescrieți codul sau să redenumiți câmpurile sau alte elemente astfel încât cititorul să înțeleagă acțiunea pe care o faceți acolo.
În multe cazuri, puteți extrage o metodă cu un nume semnificativ. Cititorul va înțelege foarte ușor ce se petrece acolo, pe baza numelor metodelor și a câmpurilor.
Adăugarea comentariilor în cod numai pentru că tu crezi că este necesar, nu este un lucru bun. Se întâmplă adesea ca cineva să adauge comentarii în cod numai pentru că el crede că așa este bine, fără a avea un motiv real. La sfârșit putem avea multe comentarii care nu sunt folositoare și numai îngreunează citirea și înțelegerea codului.
Când ai un nume bun pentru câmpul tău sau metoda ta, nu mai ai nevoie de un comentariu care să descrie care este scopul acelui câmp sau acelei metode. De exemplu, o metodă denumită "SendEmail" nu mai are nevoie de niciun comentariu adițional atunci când este apelată. Este clar din numele metodei că se trimite un e-mail.
Un alt exemplu bun este câmpul denumit vatValueForCurrentOrder. Din numele câmpului este destul de clar ce valoare este stocată în acest câmp. Nu ai nevoie de un comentariu care să spună "Valoarea comenzii curente este stocată." În acest caz, comentariul nu adaugă nicio informație valoroasă.
În multe cazuri, dezvoltatorii nu exprimă ceea ce intenționează să facă. Din această cauză, puteți găsi un comentariu care spune că este trimis un e-mail către client și poți ajunge să faci debugging și să încerci să înțelegi de ce e-mailul nu este trimis.
În sfârșit, realizezi că metoda care este apelată sub acel comentariu nu trimite un e-mail, ci numai construiește obiectul e-mail.
De obicei, în companiile și proiectele mari se impun reguli care cer ca fiecare metodă și clasă să aibă comentarii. În acest fel sfârșești prin a avea multe comentarii care nu adaugă o valoare reală. Sunt adăugate de către dezvoltatori numai pentru că așa se cere. De exemplu, o proprietate denumită Id are următorul comentariu "Obține, stabilește id-ul obiectului curent". Nicio informație utilă nu este adăugată prin acest comentariu, numai trei rânduri adiționale de comentariu care îngreunează codul.
Cum ar fi să adaugi la un constructor comentariul "Construiește o exemplificare a obiectului Foo". Să fim serioși, este clar care este scopul unui constructor. În general, constructorii nu ar trebui să fie niciodată comentați.
Acum 30 de ani, când controlul sursei nu se obișnuia la fiecare proiect, poate că era o idee bună să scrii în cod jurnalul modificărilor codului (când, ce, de ce, cine - a modificat codul). Dar acum, cu controlul sursei și alte mecanisme de detectare, nu mai are sens să facem asta.
Utilizând un sistem de control al sursei, puteți vedea și depista toate modificările efectuate asupra codului.
Încercați să evitați utilizarea marcajelor de poziție în codul vostru, cum ar fi de exemplu, să adaugi ///////// în cod pentru a găsi mai ușor o parte anume a codului.
Exemple bune de comentarii
Da, există cazuri în care comentariile sunt utile și pot adăuga valoare codului vostru.
Există cazuri când trebuie să adăugați un comentariu din motive legale. Codul se poate afla sub termenii unei licențe anume, iar acest lucru trebuie să fie specificat. În acest caz, trebuie să adăugați un comentariu care să specifice acest lucru, dar fără a adăuga acolo toți termenii licenței. Puteți indica din comentariu un document sau link-uri anume care descrie termenii licenței. Nu vreți să aveți 200 de rânduri de comentarii cu aceste informații.
Mai sunt și cazuri când un comentariu poate adăuga valoare unui cod. De exemplu, atunci când oferim mai multe informații despre ceea ce redă o metodă. Fiți atenți că există cazuri când un nume bun al unei metode poate să înlăture necesitatea comentariilor legate de valoarea redată.
Un comentariu este întotdeauna util când este exprimată intenția. Nu este important să comentăm ceea ce am făcut în cod, deoarece cititorul poate să vadă codul în sine. Este mai important să explicăm ceea ce am vrut să facem în cod.
Există cazuri în care nu putem exprima exact care este intenția noastră. Din această cauză, noi trebuie să adăugăm comentarii care să aducă o mai mare clarificare și să explice de ce nu am acționat într-un anume mod. Poate că există un bug într-o bibliotecă externă pe care a trebuit să îl evităm, sau poate clientul a avut o cerință ciudată.
Există momente când știi că anumite linii de cod sunt foarte importante și că, fără ele, aplicația s-ar putea distruge. În aceste cazuri, comentariile i-ar putea avertiza pe dezvoltatori în legătură cu importanța acelor linii de cod.
Un exemplu bun este o variabilă mutex care este folosită pentru a accesa o resursă partajată. Poate nu toți dezvoltatorii ar înțelege importanța acelui mutex și de aceea este nevoie de un avertisment.
Toate API-urile publice care sunt destinate a fi utilizate de către clienți și dezvoltatori externi ar trebui să fie documentate foarte bine. Deoarece ei nu vor putea să vadă implementarea, denumirea diferitelor clase și funcții în combinație cu comentariile ar trebui să exprime foarte clar care este scopul fiecărei metode și cum ar trebui apelată.
Imaginați-vă codul drept un text dintr-o carte. Acesta ar trebui să fie editat frumos, indentația să fie utilizată în același fel pretutindeni, după fiecare , ar trebui să existe câte un spațiu și așa mai departe.
Cel mai important lucru când vorbim de format este nu să respecți un anume standard, ci să respecți același standard peste tot. Chiar dacă ți-ai definit propriul tău stil de editare, este în regulă, atâta timp cât respecți acel format pretutindeni. Formatul codului ar trebui să ghideze dezvoltatorii spre a citi și a înțelege codul.
IMG
Imaginați-vă o carte care este scrisă cu 10 stiluri de text, caractere de dimensiuni diferite, culori diferite, aliniere și spațiere diferită. Ar fi un coșmar. Același lucru se aplică și codului.
În jurul acestui subiect există multe recomandări despre câte linii de cod ar trebui să conțină un fișier, care este numărul optim de caractere per linie. Nu veți putea găsi numărul magic, dar veți simți când numărul liniilor de cod este prea mare și derularea conținutului pe display devine enervantă.
Este recomandat să declari variabilele cât mai aproape posibil de locația unde sunt folosite. Nu vrei să declari o variabilă în linia 1 și să o utilizezi numai din linia 15.
Este de dorit să grupezi toate câmpurile în aceeași locație a codului. Câmpurile cu atribute diferite ar trebui să fie grupate împreună (vizibilitate, anvergură - static/ non-static, și așa mai departe).
Mai există un alt trend care spune că ar trebui să grupezi toate elementele unei clase pe baza funcționalității și acolo unde acestea sunt utilizate. În acest fel, vei avea o zonă în fișier cu metode și câmpuri pentru o anumită funcționalitate. Chiar dacă ideea este destul de frumoasă, este destul de greu de citit și modificat acest tip de cod, pentru că se poate întâmpla foarte ușor să omiți faptul că un câmp este deja declarat, de exemplu.
Funcțiile care sunt dependente ar trebui plasate laolaltă. Este recomandat să ai funcția copil sub funcția care o apelează. În acest fel, vei putea să citești foarte ușor codul, fără a trebui să navighezi prea mult între locații diferite în interiorul codului.
Codul cu același scop și funcție ar trebui plasat în același loc. Nu ai vrea să derulezi sau să cauți în 10 fișiere o anumită funcționalitate.
Este foarte util să respecți un standard de indentație în întregul tău cod, chiar dacă există momente când ai vrea să încalci această regulă. Prin respectarea acestei reguli vei putea mai ușor să reperezi o variabilă, o acțiune executată de o subordonată FOR (pentru) sau IF (dacă) și așa mai departe.
Cu noile IDE și unelte este foarte ușor să respecți aceeași indentație pretutindeni.
Cel mai important lucru într-o echipă este să ai un singur stil de editare care trebuie să fie respectat de către toți membrii echipei. Nu pierdeți zile întregi definind stilul de cod și editare. Există suficiente astfel de reguli deja disponibile care pot fi utilizate cu succes - nu reinventați roata încă o dată.
Este important să știți că echipe diferite pot utiliza standarde de codare diferite. Din această cauză, dezvoltatorii ar trebui să fie deschiși să accepte și să învețe alte standarde de codare, nu numai pe cel cunoscut de ei.
Comentariile și formatul codului pot face codul mai ușor de citit și de înțeles. Încercați să definiți aceste reguli la începutul proiectului și fiți pregătiți să le schimbați dacă este necesar și dacă are sens.
Nu uitați că regulile cele mai simple sunt cele mai bune!
"Nu comentați codul greșit – rescrieți-l!"
Brian W. Kernighan and P. J. Plaugher
de Ovidiu Mățan
de Mircea Vădan
