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
Dacă doriți să aflați mai multe despre mine, Cornel Fătulescu, sau proiectele în care sunt implicat, vă invit să mă descoperiți și ca Chief Platform Officer la Pentalog, să mă urmăriți pe Facebook, ca investitor la wanttolearn, să citiți unul dintre primele articole despre mine și să mă contactați urmând ghidul de pe pagina de contact.
Acest articol a fost citit de 1656 ori