Clean code o código limpio

L’ART DEL CODI NET: EL PODER DELS NOMS SIGNIFICATIUS

El clean code (o codi net) és una pràctica de programació que es basa a escriure codi clar, llegible i fàcil de mantenir. Consta de normes sobre com escriure codi. Entre elles trobem: regles d’estil com: evitar redundàncies, mantenir les funcions i mètodes en poques línies i escriure comentaris només quan sigui necessari, entre altres.

Una d’aquestes regles és cuidar la nomenclatura del nostre codi per a variables, funcions, classes…etc. La idea és usar noms correctes per a no dependre d’una documentació o comentari que embrutin el codi i que a més, portaria un manteniment extra. Amb aquesta sèrie de regles de codi net, haurem de poder llegir el codi fàcilment, com si es tractés d’un llibre per a programadors. Triar els noms correctes pot prendre temps, però val la pena, ja que en realitat estarem agilitzant el treball.

PRINCIPIS MÉS IMPORTANTS DEL CLEAN CODE O CODI NET

Hi ha una sèrie de regles d’estil que ens ajudaran a tenir noms significatius en el nostre codi. Algunes de les quals pensem més importants són les següents:

UTLITZAR NOMS AUTO DESCRIPTIUS

Recordem que el que volem és prescindir de comentaris addicionals que afegeixin complexitat a la lectura del nostre codi. Per a això, el primer i més important és que els noms que usem s’expliquin per si sols. Si en llegir el nom de la nostra variable ja sabem per a què s’utilitza, no farà falta cap comentari addicional. Simple no?

Per exemple, suposem que volem emmagatzemar els dies que porta un usuari sense modificacions. En el nostre codi el tenim en la següent variable: int d;

Però podem trobar un nom molt millor, que ens expliqui quin és el valor que emmagatzema, per exemple: int daysSinceLastModification;

D’aquesta manera, no serà necessari comentar quin guarda o per a què serveix una variable. Quan tornem a aquesta part del codi després d’un temps podrem simplement llegir-lo i ho entendrem. El mateix aplica per a les funcions i les classes, no és igual de clar user.GetThem() que user.GetAllBooks().

Clean code o código limpio

EVITAR LA DESINFORMACIÓ EN ELS NOMS

Si en el punt anterior hem aconseguit donar-li un valor i significat als nostres noms, el següent pas és que no hem de confondre al lector.

Com a programadors hem d’evitar les abreviacions en els noms. Aquestes poden semblar una bona idea al moment d’escriure el codi, però a la llarga provocaran confusions. Si per exemple tenim la variable addressDt, la part de Dt pot ser confusa Què significa Dt?DataType?DateTime? Si a més estem treballant amb ADO.NET serà de DataTable?

Per a no crear aquest tipus de confusions, hem d’evadir les abreviacions i escriure la variable completa: addressDetail.

A més, en aquest exemple hem pogut comprovar que hi ha unes certes paraules claus que signifiquen alguna cosa més per als programadors, com és el cas de DataTable. Evitem agregar paraules clau com DataTable o List si la variable no és de veritat un DataTable o una List.

ESCRIURE NOMS QUE PUGUIS PRONUNCIAR

Com a humans, estem estretament relacionats amb l’ús del llenguatge. Gran part del nostre cervell es dedica al concepte d’aquest. Per tant, el més lògic és que els noms que creem en el nostre codi siguin fàcilment pronunciables tal com ho són les paraules en el nostre llenguatge.

Anem amb un exemple. Suposem que tenim una variable que emmagatzema la quantitat que tenim d’un producte. Si a aquesta la cridem prodQnty el més segur és que acabem llegint-la alguna cosa així com “prodty” o “prodcunty”. De manera que, si estem tenint un debat sobre aquesta part del codi amb el nostre company d’equip, no podrem pronunciar aquesta variable sense semblar idiotes.

No obstant això, si canviem el nom de la variable a productQuantity, ara sí que podem tenir una conversa seriosa sobre els canvis que vulguem aplicar a aquest codi.

Utilitzar NOMS BUSCABLES

Al llarg del dia, com a programadors, farem moltes cerques en el codi. No t’adones del mal triat que està un nom fins que la cerca que estàs intentant no et facilita el trobar aquesta funció, variable… etc.

I és que, l’aplicació fa una mitjana d’acabarà sent un oceà de lletres tard o d’hora. Per aquesta raó, buscar el nom exacte de la variable que volem, si no està ben definit, pot ser com buscar una agulla en un paller.

No serà el mateix buscar WORK_DAYS_PER_WEEK que el número 5 en el codi.

La longitud d’un nom haurà d’anar directament relacionada amb l’àmbit d’aquest. Si tenim un Enum amb els dies laborables de la setmana, imagina’t l’embolic que pot ser buscar els casos d’ús mitjançant la lletra “d”. No obstant això, podrem acabar moltíssim abans si li hem posat un nom com WorkingDays.

En l’altre extrem, per a una variable numèrica que ens ajudarà a iterar un bucle for, no hi ha problema amb nomenar-la amb la lletra ‘i’ ja que s’utilitzarà en un context molt reduït. A més, en aquest cas és ja una convenció global en programació.

NOMS DE MÈTODES I CLASSES

Els noms per a les classes i els mètodes tenen una convenció dins de la sèrie de regles de codi net. Aquestes són bastant senzilles:

  • Per als noms de les classes usarem substantius o frases de nom tal com poden ser Customer, Product, UserAccount. El nom d’una classe no ha de contenir un verb.
  • Els mètodes, d’altra banda, han de tenir noms de verbs. Uns noms de mètodes perfectes per a les classes anteriors podrien ser: getName, hasStock i signOut.

UNA PARAULA PER CONCEPTE

Tria una paraula per a cada concepte i compromet-te amb ella. Has de mantenir la coherència de cada acció o concepte abstracte que tinguis en el teu codi.

Per exemple, suposem que tenim una classe User, a la qual, com ja sabem posar noms perfectes de mètodes, li agreguem el mètode saveNewPassword. Fins aquí tot genial. Més tard, treballem en una classe Bank i ens fa falta agregar un mètode per a emmagatzemar moviments en els comptes del banc. Ara optem per cridar al mètode writeMovement.

Aquest tipus d’inconsistència és el que hem d’evitar. Algú que vingui de treballar amb la nostra classe User i passi a usar la classe Bank, esperarà que el mètode correcte sigui saveMovement. Per això, per a cada concepte del codi, hem de triar una paraula i mantenir-la.

UTILITZAR NOMS DE DOMINIS DE SOLUCIONS

Els lectors del teu codi seran més programadors. El millor que pots fer com a programador en triar noms, és utilitzar termes tècnics. Així, tant els lectors com tu us podreu estalviar temps en explicacions.

Utilitza noms de termes informàtics, patrons de disseny, algorismes i altres. Un programador que estigui familiaritzat amb el patró de disseny Visitor, en llegir el nom AccountVisitor, ja es fa una idea del que es trobarà dins d’aquesta classe.

UTILITZAR NOMS DE DOMINIS DE PROBLEMES

Si no existeix un terme en la programació per al que estiguis fent, utilitza el nom del problema que resol la part en la qual estàs treballant.

D’aquesta manera, si un altre company ha de treballar amb aquest codi, podrà preguntar sobre el domini a algú que estigui familiaritzat amb aquest. I si no, almenys s’haurà delimitat aquesta part del codi a un problema en concret, llevant una mica d’esforç a l’hora d’entendre-ho.

CONCLUSIONS

Hem pogut repassar els punts més importants a l’hora de triar noms en el nostre codi i també hem pogut comprovar de primera mà el que uns simples canvis poden ajudar a la llegibilitat i el manteniment d’aquest.

Segons posem en pràctica aquestes regles, comprovarem que escriure codi net és un exercici que requereix de disciplina, constància i esperit crític. Però, val la pena per tots els beneficis que ens ofereix en escriure i mantenir una aplicació.

Finalment, m’agradaria fer un esment especial a una pràctica que crec, ens beneficiarà com a desenvolupadors. Aquesta és ni més ni menys que la regla d’or dels boy scouts americans: deixa el campament més net del que el vas trobar. És a dir, quan vagis a tocar codi ja existent, dona un cop d’ull al voltant i si veus que un nom pot millorar, no dubtis a posar-te a això.

José Álvarez – Software Developer at Itequia