Vizibilitate tuturor!

Sunt adeptul suprimării formelor fără fond cu precădere prin educație, viziune comună, focalizarea energiilor, obiectivism și foarte multă răbdare.

Documentarea codului cu comentarii

Răsfoind blogul 8thlight și citind articolul An Appeal to CS Teachers mi-am adus aminte că am fost contactat recent să răspund unei cereri atipice: o propunere de documentarea codului. Sună ciudat și inutil, dar cu toate acestea a meritat să dezbatem problema împreună.

Între manageri există un fel de preconcepție conform căreia codul trebuie să abunde de comentarii. Motivele pot fi multe, dar printre care am putut observa:

  • nu dădea bine în indicatorii de analiză statică de cod,
  • în cazul în care pleacă vreun dezvoltator să putem transfera mai repede codul către un nou venit,
  • un obiectiv dat alandala de vreun arhitect, manager sau impus la nivel de organizație,
  • exces de zel.

Astfel se creează falsa senzație că avem un cod mai bine documentat.

O parte din răspunsul meu a sunat în felul următor:

Comentariile trebuie să fie pertinente

Să spunem că avem metoda „Private Function getInvoiceById(invoiceId As Long) as InvoiceHeader …”

Ar fi inutil să adăugăm un comentariu precum „întoarce obiectul de factură în funcție de ID-ul trimis ca parametru”. N-ar aduce nicio informație în plus care să nu reiasă deja din semnătura metodei. Dacă simțim nevoia adăugării unui comentariu, poate că ar fi mai bine să corectăm codul scris.

Lipsa codului de calitate este un efect nu o cauză

Dacă nu s-au scris comentarii utile până acum, ce s-a schimbat de curând? Încă nu s-a schimbat nimic? atunci mai bine evităm să poluăm codul cu comentarii pe care va trebui să le actualizăm și pe care puțini le citesc de obicei.

O problemă și mai mare

Să spunem că comentariile sunt adăugate de prestator. Programatorii schimbă codul, dar nu și comentariile. Tot programatorii vor vedea din ce în ce mai multe comentarii care n-au nimic de-a face cu codul, și nu se vor mai deranja să le aducă la zi. Întocmai bulgărelui de zăpadă care prinde viteză și proporții mai mari la fiecare rostogolire, așa și clientul va acumula doar din ce în ce mai mult cod ilizibil și greu de menținut.

documentarea_codului_cu_comentarii_cornel_fatulescu

Documentarea codului cu comentarii

Cornel FătulescuDacă doriți să aflați mai multe despre mine, Cornel Fătulescu, sau proiectele în care sunt implicat, vă invit să mă descoperiți ca voluntar pe pagina membrilor AgileHub, asociație în care sunt cofondator, ca mentor la ScriuCod, ca CTO la Pentalog sau să citiți unul dintre primele articole despre mine și să mă contactați la pagina de contact.

Acest articol a fost citit de 969 ori