Clean Code

1. Escriu codi net que sigui llegible i mantenible

La única mesura vàlida de la qualitat del codi: WTFs/minut

La llegibilitat és primordial. El codi net ha de ser fàcilment comprensible per altres desenvolupadors. Ha de ser simple, elegant i lliure de desordre. Esforça't per escriure codi que expressi clarament la seva intenció sense necessitat de comentaris extensos. Utilitza noms de variables i funcions significatius, mantingues les funcions petites i enfocades, i organitza el codi de manera lògica.

La mantenibilitat permet l'evolució. El codi que és difícil de canviar esdevé un passiu. Dissenya el teu codi per ser flexible i modular, de manera que pugui adaptar-se a requisits canviants. Segueix principis com DRY (No et repeteixis) i SOLID per crear sistemes poc acoblats i altament cohesius. Refactora sense pietat per millorar l'estructura del codi sense canviar el seu comportament.

El codi net val la pena. Encara que escriure codi net requereix més esforç inicial, estalvia temps i maldecaps significatius a llarg termini. El codi net és més fàcil de depurar, ampliar i mantenir. Permet als desenvolupadors treballar de manera més eficient i redueix el risc d'introduir errors durant els canvis. Fes del codi net una part fonamental de la teva pràctica de desenvolupament.

2. Segueix convencions de nomenclatura significatives

El nom d'una variable, funció o classe ha de respondre a totes les grans preguntes. Ha de dir-te per què existeix, què fa i com s'utilitza.

Utilitza noms que revelin la intenció. Escull noms que transmetin clarament el propòsit i el comportament de les variables, funcions i classes. Evita noms d'una sola lletra o abreviatures críptiques. Utilitza noms pronunciables que es puguin cercar fàcilment. Per exemple:

• Dolent: d (temps transcorregut en dies)
• Bo: elapsedTimeInDays

Sigues coherent i precís. Utilitza convencions de nomenclatura coherents a tota la teva base de codi. Sigues precís per evitar ambigüitats; per exemple, utilitza distincions significatives com getActiveAccounts() i getActiveAccountInfo(). Evita codificacions o prefixos que afegeixin soroll sense valor. Els noms de classe han de ser substantius, i els noms de mètodes han de ser verbs.

La longitud del nom ha de coincidir amb l'abast. Utilitza noms més llargs i descriptius per a variables i funcions amb àmbits més amplis. Els noms curts són acceptables per a àmbits petits i locals. La longitud d'un nom ha de ser proporcional al seu àmbit d'ús. Optimitza per a la llegibilitat i la comprensió dins del context on s'utilitza el nom.

3. Mantingues les funcions petites i enfocades

Les funcions han de fer una sola cosa. Han de fer-ho bé. Han de fer-ho només.

Petit és bonic. Les funcions han de ser petites, típicament de 5 a 10 línies de llarg. Han de cabre en una pantalla i ser immediatament comprensibles. Extreu codi en funcions auxiliars ben nomenades en lloc d'escriure funcions llargues i complexes. Les funcions petites són més fàcils d'entendre, provar i mantenir.

Fes una sola cosa bé. Cada funció ha de tenir un únic i clar propòsit. Si una funció està fent múltiples coses, extreu-les en funcions separades. Símptomes que una funció està fent massa inclouen:

• Múltiples nivells d'abstracció
• Múltiples seccions o blocs de codi
• Numerosos paràmetres

Mantingues un nivell d'abstracció. Les instruccions dins d'una funció han d'estar totes al mateix nivell d'abstracció. No barregis la lògica d'alt nivell amb detalls de baix nivell. Extreu operacions de baix nivell en funcions separades. Això millora la llegibilitat mantenint les funcions enfocades i conceptuament simples.

4. Practica un format i organització adequats

El format del codi és sobre comunicació, i la comunicació és la primera ordre de negoci del desenvolupador professional.

El format coherent és important. Utilitza una indentació, salts de línia i espaiat coherents a tot el teu codi. Això millora la llegibilitat i redueix la càrrega cognitiva. Acorda't sobre estàndards de format amb el teu equip i utilitza eines automatitzades per fer-los complir. Les pautes de format clau inclouen:

• Indentació adequada
• Col·locació coherent de claus
• Trencaments de línia lògics
• Espai en blanc apropiat

Organitza el codi de manera lògica. Agrupa el codi relacionat i separa el codi no relacionat. Utilitza línies en blanc per crear "paràgrafs" entre seccions lògiques. Col·loca funcions relacionades a prop les unes de les altres. Mantingues els fitxers enfocats en un sol concepte o component. Divideix fitxers grans en altres més petits i enfocats quan sigui apropiat.

Segueix convencions estàndard. Adhereix a les convencions estàndard per al teu llenguatge i comunitat. Això fa que el teu codi sigui més familiar i accessible per a altres desenvolupadors. Per exemple, en Java:

• Els noms de classe utilitzen PascalCase
• Els noms de mètodes utilitzen camelCase
• Les constants utilitzen ALL_CAPS

5. Gestiona les dependències i evita la duplicació

La duplicació pot ser l'arrel de tot mal en programari.

Elimina la duplicació. El codi duplicat és una oportunitat perduda per a l'abstracció. Quan vegis duplicació, extreu el codi comú en una funció o classe reutilitzable. Això millora la mantenibilitat centralitzant la lògica i reduint el risc de canvis inconsistents. Tipus de duplicació a vigilar:

• Blocs de codi idèntics
• Algorismes similars amb lleus variacions
• Cadenes repetides de switch/case o if/else

Gestiona les dependències amb cura. Minimitza les dependències entre mòduls per reduir el acoblament. Utilitza la injecció de dependències i la inversió de control per fer que el codi sigui més modular i provable. Segueix el principi d'inversió de dependències: depèn d'abstraccions, no de concrecions. Això fa que el teu codi sigui més flexible i més fàcil de canviar.

Utilitza el principi del mínim coneixement. Un mòdul no ha de conèixer els detalls interns dels objectes que manipula. Això redueix el acoblament entre mòduls. Per exemple, utilitza la Llei de Demeter: un mètode només ha de cridar mètodes sobre:

• El seu propi objecte
• Objectes passats com a paràmetres
• Objectes que crea
• Els seus objectes components directes

6. Gestiona els errors amb elegància

La gestió d'errors és important, però si obscurifica la lògica, és errònia.

Utilitza excepcions en lloc de codis d'error. Les excepcions són més netes i no desordenen la lògica principal del teu codi. Permeten que la gestió d'errors estigui separada del camí feliç. Quan utilitzis excepcions:

• Crea missatges d'error informatius
• Proporciona context amb excepcions
• Defineix classes d'excepcions basades en les necessitats de qui crida

No retornis null. Retornar null condueix a excepcions de punter null i desordena el codi amb comprovacions de null. En lloc d'això:

• Retorna col·leccions buides en lloc de null per a llistes
• Utilitza el patró Null Object
• Utilitza Optional en Java o Maybe en llenguatges funcionals

Escriu primer les instruccions try-catch-finally. Comença amb el try-catch-finally quan escriguis codi que podria llençar excepcions. Això ajuda a definir l'abast i les expectatives per al codi que crida. Assegura't que els recursos es gestionen i es llencen adequadament, fins i tot en escenaris d'error.

7. Escriu proves unitàries exhaustives

El codi de prova és tan important com el codi de producció.

Segueix les tres lleis del TDD. El desenvolupament dirigit per proves (TDD) millora la qualitat i el disseny del codi:

1. Escriu una prova fallida abans d'escriure qualsevol codi de producció
2. Escriu només el necessari d'una prova per demostrar un fracàs
3. Escriu només el codi de producció necessari per passar la prova

Mantingues les proves netes i mantenibles. Aplica els mateixos estàndards de qualitat del codi a les teves proves que al teu codi de producció. Refactora i millora el codi de prova regularment. Les proves ben estructurades serveixen com a documentació i permeten una refactorització sense por del codi de producció.

Apunta a una cobertura de proves completa. Escriu proves que cobreixin casos límit, condicions de frontera i escenaris d'error, no només el camí feliç. Utilitza eines de cobertura de codi per identificar buits en la cobertura de proves. Recorda que una cobertura del 100% no garanteix un codi lliure d'errors, però proporciona confiança en la refactorització i els canvis.

8. Refactora el codi contínuament

Deixa el campament més net del que el vas trobar.

Refactora de manera oportuna. Millora l'estructura del codi sempre que treballis en un fragment de codi. Segueix la regla del Boy Scout: deixa el codi millor del que el vas trobar. Millores petites i incrementals s'acumulen amb el temps i prevenen la degradació del codi. Tècniques comunes de refactorització inclouen:

• Extreure mètodes o classes
• Canviar noms per claredat
• Simplificar condicions complexes
• Eliminar duplicació

Refactora de manera segura amb proves. Sempre tingues un conjunt sòlid de proves abans de refactoritzar. Fes canvis petits i incrementals i executa les proves amb freqüència. Això et dóna confiança que els teus canvis no trenquen la funcionalitat existent. Utilitza eines de refactorització automatitzades quan estiguin disponibles per reduir el risc d'introduir errors.

Equilibra la refactorització amb la entrega de valor. Encara que la refactorització contínua és important, no deixis que paralitzi el progrés. Apunta a "suficient" en lloc de la perfecció. Centra els esforços de refactorització en les àrees més problemàtiques o que es canvien amb més freqüència del codi. Comunica el valor de la refactorització als interessats per assegurar el suport per a la millora contínua del codi.

9. Aplica principis de programació orientada a objectes i funcional

Els objectes amaguen les seves dades darrere d'abstraccions i exposen funcions que operen sobre aquestes dades. Les estructures de dades exposen les seves dades i no tenen funcions significatives.

Utilitza els principis orientats a objectes amb saviesa. Aplica principis com l'encapsulament, la herència i el polimorfisme per crear dissenys flexibles i modulars. Segueix els principis SOLID:

• Principi de Responsabilitat Única
• Principi Obert-Tancat
• Principi de Sustitució de Liskov
• Principi de Segregació d'Interfícies
• Principi d'Inversió de Dependències

Aprofita els conceptes de programació funcional. Fins i tot en llenguatges orientats a objectes, les tècniques de programació funcional poden conduir a un codi més net:

• Funcions purament sense efectes secundaris
• Dades immutables
• Funcions d'ordre superior
• Composició de funcions

Tria l'enfocament adequat per al problema. Els paradigmes orientats a objectes i funcionals tenen cadascun punts forts i febles. Utilitza el disseny orientat a objectes quan necessitis modelar dominis complexos amb comportament. Utilitza enfocaments funcionals per a la transformació de dades i les canonades de processament. Molts llenguatges moderns suporten un enfocament híbrid, permetent-te utilitzar l'eina més adequada per a cada part del teu sistema.

10. Considera la concurrència amb cura

La concurrència és una estratègia de desacoblament. Ens ajuda a desacoblar el que es fa del quan es fa.

Entén els reptes de la concurrència. La programació concurrent introdueix complexitat i potencial per a errors subtils. Els problemes comuns inclouen:

• Condicions de carrera
• Mortals
• Senyals perduts
• Problemes de visibilitat de memòria

Separa les preocupacions de concurrència. Mantingues el teu codi relacionat amb la concurrència separat d'altre codi. Això facilita el raonament i les proves. Utilitza abstraccions com Executors, Futures i Actors per gestionar la concurrència en lloc de treballar amb fils en brut.

Prefereix la immutabilitat i les funcions purament. Els objectes immutables i les funcions purament són inherentment segurs per a fils. Eliminen molts problemes de concurrència evitant l'estat mutable compartit. Quan l'estat mutable és necessari, utilitza tècniques de sincronització adequades i considera l'ús de variables atòmiques o col·leccions concurrentes.

Última actualització: January 22, 2025