Naming Things de Tom Benner o carte mică, dar îngrijită despre denumirea identificatorilor în cod (variabile, clase, metode, deci nu pachete sau biblioteci). A intrat în lista mea de citit în urmă cu câțiva ani, când am citit postarea pe blog Naming Things de Vicki Boykis. Cartea lui Tom Benner este autopublicată și disponibilă pe Amazon (e-book și paperback) și Leanpub (e-book). Rareori cumpăr lucruri de pe Amazon și prefer să citesc pe hârtie, așa că am așteptat cu răbdare să apară un exemplar pe site-ul meu preferat de cărți second-hand.
De ce să mai citești din nou despre denumirea lucrurilor?
În acest moment, am fost expus la multe sfaturi despre denumirea lucrurilor, în Arta codului lizibil, O filosofie a designului software, Creierul programatorului… Deci, de ce să vă obosiți să citiți încă o sursă de informații pe această temă? Ei bine, am avut încredere în recomandarea lui Vicki Boykis și, din moment ce cartea este atât de scurtă – mai puțin de 100 de pagini, nu a fost un pariu periculos.
Cartea este bine organizată, ușor de citit și pare exhaustivă. Explică de ce numirea este importantă, de ce este dificilă și prezintă 4 principii pentru denumire: înțelegere, concizie, consecvență, distingere.
Iată câteva dintre atracțiile mele…
Nume proaste, aspect prost
Printre numeroasele motive pentru care numele rele sunt dăunătoare unui proiect, acesta mi-a atras atenția:
„(Un) nou venit poate dezvolta o percepție slabă asupra proiectului și, în cel mai rău caz, o percepție slabă asupra echipei.”
Care este un nume de înțeles?
„Un nume de înțeles are o înțelegere ridicată (poate fi înțeles rapid) și o reamintire ridicată (poate fi reținut cu ușurință).”
Îmi amintește de Creierul programatorului.
Cartea recomandă, de asemenea, să eviți inteligența sau conceptele irelevante: numirea lucrurilor pe baza unor glume obscure sau referințe muzicale.
Scara abstracției
Cartea recomandă utilizarea „nivelului adecvat de abstractizare”.
„Nu folosiți un nume atât de specific încât să furnizați informații care nu sunt relevante pentru public și nu folosiți un nume atât de generic încât să le ofere puține sau deloc informații relevante.”
Cartea discută apoi 4 nume pentru o funcție care elimină spațiile albe de început și de final de la un numar de telefon: process(), format(), trim_whitespace(), strip(). Se explică că alegerea corectă este format(): arată intenția funcției fără a dezvălui detalii care ar putea fi irelevante sau pot fi modificate.
booleene
Cartea recomandă să adăugați întotdeauna is_ în numele booleanilor, de ex is_valid.
De asemenea, precizează că ar trebui să fie enunțate în sens pozitiv, cu un exemplu pe care îl adaptez la R mai jos:
# Bad
if (!user_is_invalid) {
save(user)
}
# Good
if (user_is_valid) {
save(user)
}
Acest exemplu a rezonat cu mine pentru că mi se întâmplă des să creez un boolean, să îl folosesc cu un if doar ca să realizez că ar trebui să definesc contrariul acelui boolean.
Și îmi amintește, dincolo de numire, de regulile legate de negație din linters precum Jarl: comparison_negation, outer_negation.
Costul redenumirilor
Cartea discută costurile unui nume prost (care se adună în timp: înțelegere lentă, reamintire scăzută) și a unei redenumiri (cost unic). M-a făcut să mă gândesc la redenumirea pe care am făcut-o și am făcut-o în igraph, inclusiv redenumirea în lot a funcțiilor cu puncte în ele în echivalentul tip șarpe (împreună cu hamul corect al ciclului de viață 😇): funcționează pentru noi, dar și pentru menținătorii dependențelor inverse și utilizatorii direcți ai pachetului.
Concluzie
Naming Things este o lectură scurtă utilă. După ce l-am citit, simt că acord și mai multă atenție numelor din codul pe care scriam despre care îl revizuiam. 😸
