Comentariile in codul unei aplicatii

Comentariile scrise in codul unei aplicatii sunt foarte utile atat pentru cel care le scrie codul, cat si pentru ceilalti care citesc codul ulterior.

Programatorii scriu cod. Aceasta este abilitatea principala a unui programator.

Codul este citit atat de ei cat si de restul echipei de programatori de pe proiect.

Programatorii trebuie sa poata citi si analiza continuu liniile de cod create de ei sau create de catre alti programatori. Acest lucru este utill pentru a putea continua crearea codului sau pentru a-l refactoriza pe cel existent deja.

Cu cat codul este mai usor de inteles si mai rapid de parcurs, cu atat proiectul se dezvolta mai rapid si mai fluent.

Abilitatea de a scrie comentarii trebuie sa existe la fiecare programator, alaturi de abilitatea de a scrie cod. Daca esti bun la a scrie cod trebuie sa fii bun si la scrierea de comentarii in codul tau.

Fara comentarii, codul poate fi oricat de bun, ca oricum este greu de inteles de catre cei din exteriorul subiectului. Timpul de parcurgere si intelege a lui creste foarte mult.

Este foarte important ca in cod sa fie prezente comentarii precise, concise si pozitionate la locul lor. Comentariile prea multe si prea lungi incarca codul si il fac greoi. Intr-un fisier cu cod, comentariile inserate nu trebuie sa depaseasca 50% din toate liniile fisierului. Daca acest lucru se intampla, atunci ori codul nu este bine scris ori comentariile sunt ineficient scrise.

Lucrand practic pe cod, descoperi echilibrul cel mai bun intre lungimea codului si numarul de comentarii. A fi programator inseamna a sti si acest echilibru. De asemenea a fi programator inseamna de fapt a citi foarte mult cod  si a implementa linii de cod.

Cum scrii comentarii bune?

Comentariile trebuie sa fie scrise la fel in intregul proiect

Codul este impartit in diverse fisiere si mai multe fisiere intr-un director. Mai multe directoare alcatuiesc proiectul.

Sunt foarte multe fisiere intr-un proiect real. Unele sunt autogenerate de catre softurile cu care se construieste aplicatia. Ele vin cu comentarii gata inserate in continut. Incercati sa respectati felul in care sunt scrise aceste comentarii.

Comentariile trebuie sa fie scrise scurt si la obiect

Explicatiile care vin in comentariu nu trebuie sa fie o mica compunere. Ele trebuie sa fie scurte si explicite.

Daca simti ca trebuie sa faci o compunere atunci codul trebuie rescris. Ceva nu este in regula.

Comentariile trebuie sa fie un indiciu pentru ceilalti programatori in care sa se inteleaga foarte rapid si clar ce functionalitate urmeaza sa fie dezvoltata in codul pentru care a fost scris comentariul.

In general, daca codul scris este o functie, in comentariu se recomanda sa apara o descriere a scopului, parametrilor ei si rezultatului returnat de catre functie.

Daca codul scris este o clasa atunci este bine sa apara data ultimei modificari si o scurta descriere a functionalitatii dezvoltate in acea clasa.

Comentariile trebuie sa fie clare

Comentariile scrise clar va vor ajuta atat pe dumneavoastra cat si pe alti dezvoltatori ai codului, in viitor.

Comentariile se scriu in timpul redactarii codului

Nu le lasati la final pentru ca ele nu vor mai fi bine scrise.

Scrieti-le pe parcurs, in timpul creerii codului.

Unii programatori mai experimentati isi creaza anumite comentarii inca de la inceputul redactarii codului pentru a-si contura firul rosu al functionalitatii pe care incearca sa o creeze. Puncteaza astfel, in linii mari, principalii pasi pe care trebuie sa ii faca astfel incat pornind de la prima linie de cod, sa ajunga la ultima linie de cod si sa acopere toate problemele pe care trebuia sa le rezolve acea functionalitate.

O astfel de abordare este foarte eficienta dar trebuie sa ai destula de multa experienta in scrierea codului pentru a proceda astfel.

Editati comentariile pe parcursul producerii codului

Nimeni nu te opreste sa faci acest lucru. In timpul scrierii codului, procesul desfasurat de programator este unul complex.

Elaborarea unor comentarii eficiente si utile consta tocmai in redarea cat mai exacta a lucrurilor in momentul creerii codului.

Nu scrieti niste comentarii goale, fara substanta numai sa fie scrise acolo. Nimanui nu folosesc. Corectati si rescrieti pana cand sunteti convinsi ca ele vor folosi in viitor.

 

Asa cum am mai spus deja, codul trebuie sa fie simplu si clar (o cerinta de baza pe care trebuie sa o respecte un programator) si in consecinta, comentariile vor fi scurte, clare si eficiente ceea ce va duce la o lizibilitate adevarata a codului.

In concluzie,

A fi programator nu inseamna a fi un scriitor bun de cod.

A fi programator inseamna a avea o baterie intreaga de abilitati corect intelese si asimilate care sa te ajute sa scrii un cod curat, durabil, lizibil si concis. Comentariile bine scrise te ajuta sa iti atingi acest scop.