Les dues lliçons anteriors van respondre a «està ben feta?» des de dos angles: què convé fer i què convé evitar. Falta el tercer, que no produeix cap error i tanmateix decideix el futur del projecte: com es llegeix.

Un LloguerService pot complir les trenta-vuit comprovacions de 10-01, no contenir ni un dels errors de 10-02 i ser tot i així un mètode de dues-centes línies amb tres banderes booleanes, variables anomenades data i temp, comentaris que repeteixen el que el codi ja diu i un domini que és una bossa de setters. Res d'això no falla avui. El que falla és d'aquí a sis mesos, quan l'ajuntament de Ribalta demani tarifes dinàmiques i ningú no gosi tocar aquell mètode.

Aquesta lliçó tracta d'això, amb un criteri únic que travessa tots els apartats i que convé fixar abans de començar: el destinatari del codi no és el compilador, és el proper que el llegeixi. I aquest proper, sovint, ets tu d'aquí a un any, sense recordar-te de res.

1. Què significa codi net aquí
2. Noms
3. Funcions i classes
4. Una refactorització completa: LloguerService
5. SOLID a Spring, amb exemples de Ribalta
6. Comentaris
7. Gestió d'errors
8. Immutabilitat
9. Optional ben fet servir
10. El model de domini anèmic
11. Arquitectura verificable amb ArchUnit
12. Estil i automatització
13. Refactorització segura
14. Deute tècnic
15. Errors Comuns i Consells
16. Exercicis

«Codi net» se sol confondre amb «codi bonic», i no és el mateix. Un criteri operatiu, que es pot aplicar sense discutir de gustos:

La quarta és la més objectiva i la que més informació dona. Si per provar un mètode cal simular mètodes estàtics, instanciar sis col·laboradors o manipular el rellotge del sistema, el problema no és la prova: és el disseny. Va ser la raó d'injectar un Clock des de 02-01 i que SeguretatLloguers sigui un bean normal en lloc d'una expressió SpEL de tres línies. I un advertiment sobre l'abast: res d'aquesta lliçó no és qüestió d'estil personal —la indentació, les claus i la longitud de línia es resolen amb una eina a l'apartat 12 i no es discuteixen a les revisions—. El que segueix és disseny.

Anomenar és l'activitat més freqüent en programar i la que més rendiment dona per minut invertit.

CicloUrbana té una regla explícita que convé enunciar perquè no és universal: el domini s'anomena en català —Estacio, Bicicleta, Lloguer, calcularImportTotal, bicicletesDisponibles— i només es conserva l'anglès en el que pertany al framework o a una llibreria: anotacions, tipus de Spring, findById, Pageable. El motiu no és patriòtic, és de llenguatge ubic: l'ajuntament de Ribalta parla d'estacions, ancoratges i tarifes, i quan el codi fa servir aquestes mateixes paraules, la traducció mental entre la conversa i el programa desapareix. El que cal evitar a tota costa és l'híbrid: EstacioService.getEstacioByNom() obliga a canviar d'idioma dues vegades en una línia.

La diferència entre un nom i un bon nom és si obliga a llegir la implementació.

getData() falla en tres fronts: no diu quines dades, no diu d'on surten i no diu segons quin criteri es filtren. cercarAmbDisponibilitat(int bicicletesMinimes) respon als tres, i a més el nom del paràmetre converteix el número de la crida en informació: cercarAmbDisponibilitat(3) es llegeix «estacions amb almenys tres bicicletes».

Quatre regles pràctiques: res d'abreviatures llevat de les universalment conegudes (id, url, http); res de números als noms, perquè proces1 i proces2 volen dir que no saps què els distingeix; el nom indica el tipus de retorn —el que comença per es o esPot retorna boolean, el que comença per cercar pot no trobar i retorna Optional o llista—; i el mateix concepte, sempre la mateixa paraula: si és cercar, no és obtenir a la classe del costat.

La regla més útil sobre la mida d'una funció no és «menys de vint línies», sinó: totes les sentències d'un mètode han d'estar al mateix nivell de detall.

El mètode públic es llegeix com un paràgraf i s'entén en cinc segons. Qui necessiti el detall baixa un nivell; qui només vulgui saber què passa, no hi baixa.

Zero, un o dos arguments és l'ideal; tres és acceptable si pertanyen al mateix concepte; amb quatre o més gairebé sempre falta un objecte que els agrupi.

Una bandera booleana és un argument que fa que el mètode faci dues coses diferents, i té tres defectes: a la crida no es llegeix res (finalitzar(9L, true) no diu què és true), obliga a un if a dins que separa dos fluxos que ja són dos mètodes, i creix: demà hi ha dues banderes i quatre combinacions, de les quals dues no tenen sentit.

«Una classe, una responsabilitat» se cita molt i s'aplica malament, perquè «responsabilitat» és vague. La formulació operativa és millor: una classe ha de tenir una sola raó per canviar, és a dir, un sol interlocutor que pugui demanar modificar-la. Si LloguerService canvia quan l'ajuntament revisa les tarifes, quan facturació canvia el format de la factura i quan el proveïdor de correu canvia la seva API, té tres raons per canviar i tres persones diferents demanant-les. L'apartat següent ho arregla.

Partim d'una versió real i versemblant de LloguerService.finalitzar: funciona, passa les proves i fa massa coses.

Les cinc responsabilitats són cinc raons diferents per canviar aquesta classe, i cadascuna té un interlocutor diferent: validar les regles de finalització (l'ajuntament), calcular l'import (el departament de tarifes), aplicar el recàrrec per excés (l'ajuntament, en una altra reunió), mutar l'estat del lloguer i la bicicleta (l'equip de domini) i notificar i mesurar (màrqueting i operacions).

L'if/else if/else reimplementa el que SelectorTarifa i les tres CalculadoraTarifa de 02-02 ja feien. És duplicació pura, i pitjor: una segona font de veritat que pot divergir de la primera. Les quinze línies es converteixen en selectorTarifa.perUsuari(lloguer.getUsuari()).calcular(durada).

L'if (minuts > 120) és una regla de negoci amagada en un servei. Com que el sistema de tarifes ja és extensible per disseny, el recàrrec encaixa com a decorador:

Ara el recàrrec es prova sol, es combina amb qualsevol tarifa present o futura i es configura per propietats. LloguerService deixa de saber que existeix.

Els sis setters consecutius són el símptoma del model anèmic de l'apartat 10. L'operació «finalitzar un lloguer» pertany a Lloguer, que és qui coneix els seus invariants:

Cal notar el que s'hi guanya: la comprovació de «ja ha finalitzat» deixa de dependre que el servei se'n recordi. Qualsevol camí que cridi finalitzar l'aplica.

El correu i la mètrica se separen a un esdeveniment en AFTER_COMMIT, com ja vam establir a Transaccions i Tasques Programades i Asincronia.

I la condició sense la qual res d'això no es fa: les proves del mòdul 6 estaven en verd abans de començar i van continuar en verd després de cada pas. Sense elles, aquesta refactorització és una reescriptura a cegues.

Dos malentesos que convé aclarir. DIP no vol dir «una interfície per classe»: vol dir que la dependència apunta cap a l'abstracció quan hi ha una frontera real. LloguerService depèn de CalculadoraTarifa perquè hi ha tres implementacions i n'hi haurà més; una ILloguerService amb una sola implementació és cerimònia sense benefici. I LSP és el més ignorat i el que produeix fallades més rares: el seu incompliment típic no és d'herència, sinó de contracte —una implementació que retorna null on les altres retornen llista buida, o que llança excepció on les altres retornen zero—, i el consumidor, escrit contra el comportament de la primera, es trenca amb la segona.

Un comentari és un deute de manteniment: no el comprova el compilador, no l'executa cap prova i envelleix en silenci. Per això el criteri és exigent.

El javadoc que val la pena és el de les fronteres: interfícies públiques, contractes de domini i qualsevol mètode el comportament del qual no sigui evident en els casos límit —CalculadoraTarifa.calcular documenta què passa amb durada zero, perquè això no és a la signatura—. En canvi, un /** Retorna el nom. @return el nom */ sobre getNom() només afegeix línies.

Excepcions específiques del domini, no genèriques. throw new RuntimeException("Error") obliga qui la captura a llegir el missatge per saber què va passar. La jerarquia de 03-06 —CicloUrbanaException amb RecursNoTrobatException, ConflicteRecursException, EstacioPlenaException i BicicletaNoDisponibleException— permet que el @RestControllerAdvice tradueixi cadascuna al seu codi HTTP sense ni un if sobre cadenes.

No facis servir excepcions per al flux normal. «No hi ha bicicletes disponibles» en una estació concorreguda no és excepcional: passa cent vegades al dia. Una excepció costa construir la traça de pila i, sobretot, comunica una cosa equivocada al lector; si el cas és esperable, retorna Optional o un tipus resultat. I no capturis Exception: atrapa també el que no saps gestionar i ho converteix en un log. Captura el que pots tractar, i deixa pujar la resta.

Missatges útils. "Error" no serveix de res; "L'estació 3 és plena: 18 bicicletes per a 18 ancoratges" diu què va passar, amb quines dades, i permet reproduir-ho. Amb una condició que no es pot oblidar: el missatge que va al client i el que va al log no són el mateix. Al log, el detall; al client, la versió sense informació interna.

Un objecte immutable no pot estar en un estat invàlid després de construir-se, és segur entre fils sense raonar res i no pot canviar entre el moment en què es valida i el moment en què es fa servir —una font real de vulnerabilitats—.

record per a DTOs i objectes de valor. Tots els DTOs de CicloUrbana ho són, amb el constructor compacte com a lloc natural per normalitzar; i també els objectes de valor del domini, com UbicacioResponse. Col·leccions immutables als retorns, perquè retornar la llista interna permet que qui la rep la modifiqui per l'esquena:

I el límit honest: les entitats JPA no poden ser immutables. Hibernate necessita un constructor sense arguments i modifica l'estat en carregar i en aplicar canvis. La resposta no és forçar la immutabilitat, sinó controlar la mutació: camps privats, sense setters públics indiscriminats, i mètodes amb nom de negoci —finalitzar, ancorarA, marcarAvariada— que són els únics que canvien l'estat i que poden protegir els invariants.

Optional es va introduir per a un cas concret —el retorn d'un mètode que pot no trobar res— i es fa servir sovint per a tres més, on fa nosa.

I l'antipatró més freqüent de tots: .get() sense comprovar, que converteix un cas previst en una NoSuchElementException amb 500 i traça al log.

orElseThrow, orElseGet, map, filter i ifPresent cobreixen pràcticament tot. Un detall que es passa per alt: orElse avalua sempre el seu argument, fins i tot quan hi ha valor, així que si construir l'alternativa és car ha de ser orElseGet amb un proveïdor mandrós.

Un model anèmic és aquell en què les entitats només tenen dades —camps, getters i setters— i tota la lògica viu als serveis. És l'estil per defecte de la majoria dels projectes Spring, i mereix una discussió honesta perquè no sempre està malament.

El cas a favor de posar comportament al domini. Compara les dues maneres de finalitzar un lloguer:

Quatre diferències que importen. L'invariant viatja amb la dada: la comprovació de «ja ha finalitzat» s'aplica per qualsevol camí, no només pel que se'n va recordar d'escriure-la. L'entitat no pot quedar a mitges: amb setters públics, un mètode pot fixar l'import i oblidar l'estat, i res no ho impedeix. El nom és en el llenguatge de l'ajuntament, no en el de la base de dades. I es pot provar sense res: Lloguer.finalitzar és una prova unitària d'un mil·lisegon.

El cas a favor del model anèmic existeix i no convé menysprear-lo:

El criteri pràctic de CicloUrbana, que és un punt intermedi defensable: les regles que depenen només de l'estat del mateix agregat van a l'entitat —finalitzar, esPotLlogar, esPlena, ancorarA—; les que necessiten col·laboradors o creuen agregats van al servei —seleccionar la tarifa, verificar que no hi ha un altre lloguer obert, comprovar permisos—. Amb aquesta divisió, Lloguer no coneix cap repositori i LloguerService no manipula estat a base de setters.

Les regles de dependència de 10-01 —el controlador no toca el repositori, el domini no importa el framework— són acords que s'incompleixen tard o d'hora si depenen que algú se n'adoni en una revisió. ArchUnit les converteix en proves.

Amb la dependència com.tngtech.archunit:archunit-junit5:1.3.0 en àmbit test, les regles s'escriuen com a camps estàtics anotats amb @ArchTest:

Cinc regles, un fitxer, i a partir d'aquell moment ./mvnw test es posa en vermell el dia que algú les incompleixi, amb un missatge que diu quina classe, quina dependència i —gràcies al because— per què està prohibida. És la diferència entre una convenció documentada i una convenció que es compleix. Tres consells perquè la inversió no es giri en contra: comença per tres o quatre regles, les que de debò fan mal si es trenquen; escriu sempre el because, perquè el missatge de fallada és l'única cosa que veurà qui la incompleixi d'aquí a un any; i si una regla necessita excepcions, declara-les explícitament en lloc d'esborrar la regla sencera.

L'estil —on van les claus, quants espais, l'ordre dels import, la longitud de línia— és la discussió amb pitjor relació entre temps invertit i valor obtingut de tota l'enginyeria de programari. La solució no és acordar un estil: és delegar-lo en una eina.

./mvnw spotless:apply formata tot el projecte i ./mvnw spotless:check falla si alguna cosa no ho està, cosa que executa la canonada de 08-05 a cada canvi.

Per què l'estil no es discuteix a les revisions. Un comentari que diu «falten dos espais» consumeix l'atenció que hauria d'anar a la lògica, genera fricció i no aporta res que una eina no faci de franc. Amb Spotless a validate, el codi arriba ja formatat i la revisió s'ocupa del que cap eina no detecta: si el disseny és correcte, si el nom revela la intenció i si falta un cas límit. I l'ordre importa en adoptar-ho: primer s'aplica el formatador a tot el projecte en un commit dedicat, sense cap canvi funcional, i només després s'activa la comprovació; barrejar reformatatge i lògica produeix diferències irrevisables.

Refactoritzar és canviar l'estructura interna sense canviar el comportament observable, i la definició conté el seu propi requisit: per saber que el comportament no ha canviat, cal poder comprovar-ho.

Les quatre regles, en ordre d'importància:

1. Si no hi ha proves, la primera tasca és escriure-les. No les de tot el sistema: les del comportament que mouràs. S'anomenen proves de caracterització i afirmen el que el codi fa avui, incloses les seves raresses. Sense elles no estàs refactoritzant, estàs reescrivint.
2. Un pas cada vegada, amb les proves entremig. La refactorització de l'apartat 4 van ser quatre passos, cadascun amb la suite en verd. Si el pas 3 trenqués alguna cosa, sabries exactament quin va ser.
3. No barregis refactorització i funcionalitat al mateix commit. Un canvi que mou dues-centes línies i a més arregla una fallada és irrevisable: ningú no pot distingir el moviment del canvi.
4. Confia en l'IDE per al que és mecànic. Reanomenar, extreure mètode o classe, canviar signatura i introduir paràmetre són transformacions que l'IDE fa sense equivocar-se; fer-les amb cerca-i-substitució és on apareixen els errors.

Quan refactoritzar. La resposta sostenible no és «reservem un sprint»: és la regla del campament, deixar el codi una mica millor de com el vas trobar cada vegada que el toques per un altre motiu. Un sprint de refactorització competeix amb funcionalitat i sempre perd; una millora de deu minuts dins d'una tasca que ja estaves fent, no competeix amb res.

La metàfora és exacta i per això funciona: prens prestat temps avui i pagues interessos cada vegada que toques aquell codi. Com la financera, hi ha deute raonable i deute ruïnós.

Com es reconeix. Quatre senyals: una estimació que creix sense que el requisit creixi; un fitxer que apareix al 80 % dels commits; una part del codi que «només toca en tal»; i la frase «no ho toquis, que funciona», reconeixement explícit que ningú no ho entén.

Com es registra. Un // TODO sense data ni responsable és decoració: als sis mesos n'hi ha cent quaranta i ningú no els llegeix. El que sí que funciona:

La diferència amb un TODO és que té destinatari, cost i impacte, que és la informació necessària per prioritzar-lo davant d'una funcionalitat; i va acompanyat d'una fitxa al mateix sistema on viu la resta de la feina, perquè un deute que només existeix al codi no es planifica mai.

Quan es paga. Tres moments, i cap no és «quan hi hagi temps»: quan tocaràs aquella zona per un altre motiu —l'interès es paga sol—; quan bloqueja alguna cosa que l'ajuntament sí que vol; i quan el cost dels interessos supera el de l'amortització, cosa que es detecta mesurant, no discutint. El deute que no molesta ningú pot quedar-se: no tot el millorable mereix ser millorat.

Confondre codi net amb codi «elegant». Una cadena de cinc stream() imbricats pot ser molt enginyosa i il·legible. Si cal llegir-la tres vegades, un bucle amb noms clars és millor codi.

Refactoritzar sense proves. És reescriure amb un altre nom. Si no hi ha proves, escriu-les abans: primer les de caracterització, després el canvi. I aplicar SOLID com a ritual —una interfície per classe, un mapejador per DTO, una fàbrica per servei— no és disseny: és cerimònia. Cada abstracció ha d'estar pagant alguna cosa concreta.

Comentar el que es pot anomenar. Si necessites un comentari per explicar què fa un bloc, gairebé sempre el que necessites és extreure aquell bloc a un mètode amb aquell nom. I deixar codi comentat «per si de cas» només genera dubtes sobre si hauria d'estar actiu: és al control de versions.

Confondre el model ric amb ficar repositoris a les entitats. Una entitat que injecta un repositori és pitjor que el model anèmic: barreja persistència i domini i fa impossible provar-la aïlladament.

Consell: la millor prova de llegibilitat és llegir-ho en veu alta. Si lloguer.finalitzar(desti, fi, importTotal) es llegeix com una frase de l'ajuntament i processar(a, true, 2) no, ja tens la resposta sense discutir d'estil.

Consell: escriu el codi pensant en qui l'esborrarà. El codi fàcil d'esborrar —fronteres clares, poques dependències entrants— és el mateix que és fàcil de canviar: si eliminar TarifaJubilat és esborrar una classe, el disseny és bo.

Consell: la revisió de codi s'ocupa del que cap eina no veu. Spotless mira el format, ArchUnit les dependències, SpotBugs els errors probables i JaCoCo la cobertura. El que queda per a les persones és si el nom revela la intenció, si l'abstracció és la correcta i si falta un cas límit. Això és exactament on una revisió aporta valor.

Refactoritza aquesta classe aplicant el que hem vist: noms, nivell d'abstracció, banderes booleanes, Optional, gestió d'errors i model de domini. Justifica cada canvi.

Escriu quatre regles d'ArchUnit que protegeixin decisions preses al llarg del curs, diferents de les cinc de l'apartat 11. Per a cadascuna, indica quina decisió protegeix, en quina lliçó es va prendre i quin missatge donaria en fallar.

Per a cadascuna d'aquestes sis regles de negoci de CicloUrbana, decideix si ha de viure a l'entitat o al servei, i justifica-ho amb el criteri de l'apartat 10: (1) una bicicleta amb menys del 20 % de bateria no es pot llogar; (2) un usuari no pot tenir dos lloguers oberts alhora; (3) una estació és plena quan les seves bicicletes ancorades igualen la seva capacitat; (4) l'import depèn del tipus de tarifa de l'usuari; (5) un lloguer finalitzat no pot tornar a finalitzar-se; (6) només un operari pot marcar una bicicleta com a avariada.

Solució 1

Els deu canvis, justificats.

I el canvi de fons: la lògica de tancament s'ha mogut a Incidencia, on l'invariant «no es tanca dues vegades» s'aplica per qualsevol camí.

Solució 2

Per què aquestes quatre i no unes altres: les quatre protegeixen decisions que s'incompleixen per descuit i no produeixen cap error immediat. Una regla d'ArchUnit sobre alguna cosa que ja falla en compilar no aporta res; el seu valor és exactament en els acords silenciosos. I el because no és decoratiu: és l'única cosa que veurà d'aquí a dos anys qui la incompleixi, així que convé incloure-hi la raó concreta o la lliçó, no un «està prohibit».

Solució 3

El patró que emergeix, i que és la resposta de l'exercici: la regla viu a l'entitat quan es pot avaluar amb el que l'entitat ja té al davant. Tan bon punt cal consultar una altra cosa —un altre agregat, un servei, l'usuari autenticat— puja al servei. El cas 1 sol generar discussió, perquè es podria argumentar que el llindar és configuració i per tant la regla és del servei; passar-lo com a argument manté l'entitat neta i la regla al costat de la dada. Quan dubtis, la pregunta útil és: puc provar aquesta regla amb un new i res més? Si la resposta és sí, pot viure a l'entitat.

El codi de CicloUrbana ja no només funciona i evita els errors coneguts: es pot llegir. I el criteri que ho governa tot és un de sol, el que obria la lliçó: el destinatari no és el compilador, és el proper que el llegeixi, amb la propietat més objectiva —la comprovabilitat— com a termòmetre: si provar alguna cosa exigeix acrobàcies, el problema és el disseny.

Saps anomenar amb la convenció del curs —domini en català, framework en anglès, sense híbrids— i distingir getData() de cercarAmbDisponibilitat(int bicicletesMinimes), que respon a què, d'on i segons quin criteri. Escrius funcions amb un sol nivell d'abstracció, on el mètode públic explica la història i els privats la detallen, i saps per què una bandera booleana és en realitat dos mètodes que encara no s'han separat. Has vist la refactorització completa de LloguerService.finalitzar en quatre passos —extreure el càlcul a SelectorTarifa, convertir el recàrrec en el decorador TarifaAmbRecarrecPerExces, moure el comportament a Lloguer.finalitzar(...) i treure els efectes secundaris a l'AFTER_COMMIT—, de trenta-vuit línies i cinc raons per canviar a onze línies i una, amb la condició innegociable de tenir les proves en verd abans i després de cada pas.

Tens SOLID aterrat a Ribalta amb els seus dos malentesos aclarits —DIP no és una interfície per classe, i LSP s'incompleix gairebé sempre per contracte i no per herència—; el criteri per als comentaris, que documenten el perquè i mai el què; la gestió d'errors amb excepcions del domini, sense fer-les servir per al flux normal, sense capturar Exception i amb missatges diferents per al log i per al client; la immutabilitat amb record i col·leccions de només lectura, i el seu límit honest a les entitats JPA, on la resposta no és la immutabilitat sinó la mutació controlada per mètodes amb nom de negoci; i Optional al seu únic lloc correcte, el retorn, amb orElseThrow substituint el .get() que converteix un 404 en un 500. I tens la discussió honesta sobre el model anèmic, amb el criteri de CicloUrbana com a punt intermedi defensable: les regles que depenen només de l'estat del mateix agregat van a l'entitat, les que necessiten col·laboradors o creuen agregats van al servei.

Tanquen la lliçó les tres peces que converteixen tot l'anterior en alguna cosa que se sosté sola: ArchUnit, que transforma les regles de dependència en proves que es posen en vermell amb un missatge que explica el perquè; Spotless, Checkstyle i l'anàlisi estàtica, que treuen l'estil de les revisions perquè aquestes s'ocupin del que cap eina no veu; i la refactorització segura recolzada en el mòdul 6, amb la regla del campament com a forma sostenible de millorar i amb el deute tècnic registrat amb destinatari, cost i impacte en lloc d'amb TODO decoratius —i amb el permís explícit de deixar sense pagar el deute que no molesta ningú—.

Amb això es tanca la reflexió sobre com està feta CicloUrbana. Durant deu mòduls hem construït la xarxa de Ribalta capa per capa i mai no l'hem mirada sencera. La lliçó Projecte Final: Recorregut Complet de CicloUrbana fa exactament això: l'arquitectura final en un diagrama, l'estructura completa del repositori, el recorregut d'un POST /api/v1/lloguers pas a pas des del balancejador fins a la mètrica —citant a cada pas la lliçó on es va estudiar—, el mapa de què va construir cada mòdul, les decisions de disseny amb les seves alternatives i les seves contrapartides, el pom.xml i l'application.yml finals comentats, com posar en marxa el projecte sencer des de zero, i cap a on continuar ampliant-lo.