El toolkit funciona sol, però la pregunta que tancava el Mòdul 7 continua oberta: és mantenible? D'aquí a sis mesos, a les tres de la matinada, amb el vigilant avisant que la còpia de seguretat ha fallat, algú —probablement tu— obrirà copia.sh i haurà d'entendre en dos minuts què fa la línia 47. Si aquesta línia diu d=${f##*/}; e=${d%%.*}, no se'n sortirà. En Bash la llegibilitat no és estètica: és la diferència entre arreglar una incidència i provocar-ne una altra. Aquesta lliçó converteix aquesta intuïció en una guia d'estil concreta i en una refactorització real del codi que ja tens escrit.

1. Per què en Bash la llegibilitat és supervivència
2. Què vol dir «llegible» de manera mesurable
3. Noms i espais de noms
4. Format: indentació, longitud de línia i continuació amb \
5. Claus, claudàtors dobles i uniformitat
6. L'estructura canònica d'un script
7. Comentaris: el perquè, no el què
8. Funcions curtes i clàusules de guarda
9. Taula d'«això no / això sí» i missatges de sortida
10. La guia d'estil de l'equip i una refactorització real

Tots els llenguatges premien el codi clar, però Bash té tres agreujants que ho converteixen en obligació:

• La sintaxi és densa per disseny. ${enviament##*/}, 2>&1, "${arr[@]}", <( ). Has après totes aquestes construccions en aquest curs, però cap no s'explica sola.
• No hi ha compilador ni tipus que et protegeixin. Un error de nom en Python peta en executar-se; en Bash, $carpeta_desti mal escrit s'expandeix a la cadena buida i rm -rf "$carpeta_desti"/* esborra /*. L'únic mecanisme de defensa és que un humà llegeixi el codi i vegi la fallada.
• Els scripts d'operacions es llegeixen sota pressió. Ningú no obre vigilant.sh un dimarts tranquil per curiositat: s'obre quan alguna cosa està trencada, amb pressa i sense marge d'error.

A això s'hi suma una realitat incòmoda: els scripts viuen molt més del que estava previst. informe-diari.sh va néixer com a deu línies per sortir del pas i avui publica l'informe que llegeix la direcció cada matí. El codi temporal és el que dura més.

«Llegible» sona subjectiu, però aterra en criteris comprovables en trenta segons:

La prova definitiva no és una mètrica sinó una pregunta: pot una altra persona de l'equip modificar aquesta funció sense preguntar-te res? Si la resposta és no, el codi no és llegible per molt que a tu t'ho sembli.

El nom és el comentari que mai no queda obsolet:

Tres regles. Les variables van en minúscules, perquè les majúscules estan reservades per convenció a l'entorn i a les constants; si dius PATH a la teva variable de camins, trenques l'script sencer. Les funcions comencen per verb (veloz_calcula_…, veloz_llegeix_…, veloz_requereix), perquè una funció fa alguna cosa; si no trobes el verb, probablement en fa dues. I el prefix veloz_ de 05-06 no és decoració: en fer source lib/comu.sh totes aquestes funcions entren a l'espai global del shell, i sense prefix una log teva xocaria amb qualsevol altra log. Sobre la longitud: i està bé a for i in {1..3}; f no està bé si s'utilitza trenta línies més avall. El nom ha de créixer amb la distància entre la seva definició i el seu darrer ús.

Indenta amb 4 espais (el que utilitza aquest curs) o amb 2, però tria'n un i no els barregis mai. Els tabuladors donen problemes dins dels here-documents i es veuen diferents a cada editor. Això no es discuteix a cada revisió: es fixa un cop i ho aplica una eina (shfmt, a 08-05).

Dos detalls importen. El primer és un parany clàssic: la barra invertida ha de ser l'últim caràcter de la línia. Si hi deixes un espai al darrere, Bash escapa aquest espai en comptes del salt de línia, l'ordre es parteix en dues i apareix un error incomprensible del tipus --file: no s'ha trobat l'ordre. És invisible a l'ull; ShellCheck ho detecta (SC1101). El segon: en una canonada pots prescindir de la barra si talles després de la |, perquè una línia que acaba en | ja continua sola. Posar la | al principi de cada línia, com a l'exemple, és més llegible perquè alinea verticalment les etapes, però exigeix la barra invertida.

Hi ha dues escoles: claus sempre (uniformitat absoluta, més soroll visual) o només quan aclareixen o són obligatòries. Aquest curs segueix la segona; el que no és opcional és ser uniforme dins d'un mateix fitxer. Amb les condicions la decisió ve de 03-03: fes servir [[ ]] sempre. No només perquè evita la divisió en paraules i admet =~ i &&, sinó per uniformitat: si el 90 % del toolkit fa servir [[ ]], el [ ] restant fa que el lector s'aturi a preguntar-se per què és diferent. Sorprendre el lector és un defecte.

Tots els scripts del toolkit segueixen el mateix ordre. Quan obres flota.sh saps que la configuració és a dalt i main a baix, i trobes el que busques sense llegir el fitxer sencer.

De dalt a baix: el shebang portable (03-01); la capçalera de documentació amb ús, opcions, codis de sortida i autoria —el primer que llegeix qui obre el fitxer, i que us() reaprofita amb sed (06-02) per no duplicar el text—; set -euo pipefail amb les cauteles de 05-03; les constants agrupades i readonly; el source de les llibreries fent servir SCRIPT_DIR per no dependre del directori de treball (05-06); les funcions; i main "$@" com a última línia del fitxer, que garanteix que res no s'executi fins que l'script estigui completament llegit (04-02).

El codi diu què fa; només un comentari pot dir per què. Els valuosos documenten una decisió no òbvia, una limitació d'una eina externa, una referència a un incident o una advertència («no canviïs l'ordre: flock s'ha d'adquirir abans de crear el temporal»). I hi ha una cosa pitjor que no comentar: el comentari que menteix. Un que diu «avisa si el disc passa del 80 %» al costat d'un codi que compara amb 90 és un parany actiu, perquè el lector s'hi refia i no ho comprova. Quan canviïs el codi, canvia el comentari en la mateixa edició o esborra'l. Per a les funcions públiques de lib/comu.sh, capçalera amb format fix:

Signatura, què fa, què escriu a stdout, quins codis retorna. Quatre línies que estalvien obrir la implementació.

Una funció ha de fer una cosa i el seu nom ha de dir quina. El símptoma que en fa dues és que a la seva descripció hi apareix una «i»: «llegeix el CSV i genera l'informe». El límit pràctic: si no cap en una pantalla, extreu. Extreure és mecànic: (1) localitza el bloc coherent, les seves entrades —seran arguments— i la seva sortida —anirà a stdout—; (2) mou-lo a una funció amb nom de verb, declarant local tot el que és intern (04-02); (3) executa l'script i confirma que continua donant el mateix. El tercer pas se'l salta tothom i és l'únic que garanteix que la refactorització no ha canviat res; a 08-06 l'automatitzarem amb Bats.

L'altre enemic és la imbricació: a partir del tercer nivell has de pujar amb la mirada per saber en quina branca ets. Reprenent les clàusules de guarda de 03-04, aquest bloc de quatre nivells amb la feina útil al fons…

…es converteix en això, amb un sol nivell d'indentació i errors que diuen quin és el fitxer:

El patró és: primer tot el que desqualifica l'entrada, després la feina.

Reescriptures que apareixen un cop i un altre a les revisions de codi de Bash:

Un script d'operacions té dos públics i cal servir-los tots dos: l'humà vol llegir i la màquina —el vigilant, un grep, el journal— vol analitzar. La solució és la de 07-04: una línia amb estructura fixa i camps separats, que continua sent llegible (2026-08-03T09:15:22+02:00 [INFO] informe-diari: enviaments processats: 1284). Tres regles convé formalitzar-les: els diagnòstics van a stderr i les dades a stdout (02-04), perquè dades=$(script) no capturi avisos; els errors diuen què ha fallat, amb quin valor i què cal fer («no es pot llegir /srv/veloz/dades/enviaments.csv: comprova els permisos», no «error»); i el codi de sortida acompanya sempre el missatge (05-03), perquè qui crida l'script no llegeix text.

Tot l'anterior cap en un ESTIL.md dins del repositori, al costat del codi —el posarem sota Git a 08-04—. Una pàgina amb les decisions preses i, sobretot, amb les excepcions justificades que l'equip hagi acordat. És un document viu: quan una discussió es repeteix per segona vegada en una revisió, la decisió s'escriu allà i deixa de discutir-se. Com a referència externa, la Google Shell Style Guide és el document més utilitzat del sector i una bona base, encara que convé adoptar-la amb criteri: fixa coses útils (local, main al final, longitud màxima) i d'altres discutibles (2 espais, 80 columnes). L'important no és quina guia tries, sinó que n'hi hagi una i que l'apliqui una eina en lloc d'una persona: d'això se n'encarrega shfmt, a 08-05.

Aquesta funció d'informe-diari.sh fa des del Mòdul 4 que no es toca:

I així queda després d'aplicar la guia:

Decisió per decisió: el nom passa de gen a resumeix_lliuraments, verb primer i sense ambigüitat. Les globals T/E passen a local amb noms complets, cosa que a més evita trepitjar variables de l'script. La validació puja al principi com a clàusula de guarda, amb ${1:?} (03-06) i un missatge que inclou el camí. El bucle while read de sis camps —cinc sense fer servir— se substitueix per un sol awk (06-01): més curt, més ràpid (ho mesurarem a 08-02) i sense trencar-se amb camps buits. L'obsolet `expr` desapareix i les cometes invertides deixen pas a $( ), que s'imbrica i es llegeix. El percentatge es delega en veloz_percentatge, que ja existeix i està provada, en comptes de reimplementar-lo amb bc. La sortida deixa de ser una frase decorada i passa a tres camps que qui crida formata com vulgui i read trosseja sense esforç. I els codis de sortida distingeixen «no puc llegir» de «no hi ha dades», que operativament són incidències molt diferents.

• Espai darrere de la barra invertida. L'error més frustrant de la lliçó, perquè és invisible. Configura l'editor perquè marqui els espais finals i deixa que ShellCheck (SC1101) els caci.
• Refactoritzar sense poder comprovar. Reescriure a ull i desplegar és tan arriscat com no refactoritzar. Desa la sortida abans (./informe-diari.sh > /tmp/abans.txt), refactoritza i compara amb diff.
• Confondre «curt» amb «llegible». [[ -f $f ]]&&. $f||exit 1 és curtíssim i illegible. L'objectiu és la claredat, no la brevetat: els caràcters són gratis.
• Consell: llegeix el teu script en veu alta. Si en arribar a una línia t'has d'aturar a desxifrar-la, allà hi falta un nom millor o un comentari que expliqui el perquè.
• Consell: el millor moment per refactoritzar és quan vas a tocar el codi. No obris una tasca de «netejar el toolkit»; neteja la funció que ja estaves modificant.

Exercici 1. Reescriu aquesta funció aplicant la guia: nom, local, clàusules de guarda, [[ ]], cometes, printf i capçalera de documentació.

Exercici 2. Localitza els cinc defectes d'estil d'aquest fragment i corregeix-los, explicant-los un per un.

Solució 1.

Nom descriptiu amb verb; local amb ${1:?} per fallar aviat si falta l'argument; guardes en lloc d'imbricació; [[ ]] amb la variable entre cometes, perquè sense cometes un camí amb espais trencaria el test; printf en comptes d'echo -e, que no és portable; els errors a stderr via veloz_log_error per no contaminar la sortida útil; dos codis diferents perquè «no existeix» i «no puc escriure» s'arreglen de manera diferent; i capçalera fixa.

Solució 2.

Els cinc defectes: (1) for f in $(ls ...) recorre la sortida d'ls, que es parteix pels espais; el glob directe és correcte i, a més, no crea processos. (2) cat | grep | wc -l són tres processos on n'hi ha prou amb grep -c. (3) El temporal /tmp/c és innecessari, no és únic —dues execucions simultànies es trepitgen— i és insegur (ho veurem a 08-03); una variable ja fa el fet. (4) if [ $? -eq 0 ] comprova el codi de l'última ordre de la canonada, que era wc, no grep: sempre dóna 0 i la condició no comprova res. (5) Les variables sense cometes. El || true és necessari perquè grep -c retorna 1 quan no troba res i amb set -e això avortaria el bucle (05-03); la guarda [[ -f ]] cobreix el cas que el glob no encaixi amb cap fitxer.

En Bash la llegibilitat és defensa activa: sense compilador ni tipus, l'únic filtre entre una $carpeta mal escrita i un rm -rf / és que algú llegeixi el codi i l'entengui. «Llegible» es mesura: funcions que caben en una pantalla, tres nivells d'imbricació com a màxim, línies de menys de cent columnes i cap comentari que repeteixi el que el codi ja diu. Les convencions del toolkit són minúscules per a les variables, MAJÚSCULES readonly per a les constants, verb al principi de cada funció i prefix veloz_ per no xocar en fer source. El format es fixa un cop —4 espais, [[ ]] sempre, claus quan aclareixen, continuació amb \ sense espai al darrere— i l'aplica una eina, no una discussió. Tots els scripts comparteixen la mateixa estructura: shebang, capçalera de documentació amb ús i codis de sortida, set -euo pipefail, constants, source de llibreries, funcions i main "$@" a l'última línia. Els comentaris expliquen el perquè —la decisió, la limitació, l'incident— i s'actualitzen amb el codi, perquè un comentari que menteix és pitjor que cap. Les funcions fan una sola cosa, i quan apareix una «i» a la seva descripció s'extreuen; la imbricació profunda es dissol en clàusules de guarda que treuen els errors al principi. La taula de reescriptures resumeix la resta: if ordre en comptes de $?, glob en comptes d'ls, printf en comptes d'echo -e, grep -c en comptes de grep | wc -l. I la refactorització de resumeix_lliuraments demostra que llegibilitat i qualitat arriben juntes: la versió clara és també més curta, més ràpida i amb millors codis d'error.

Just aquí apareix un dubte raonable: hem substituït un bucle while read per un awk afirmant que és «més ràpid». Quant més? Importa amb 1.200 enviaments? I amb 500.000? Això no s'endevina, es mesura. La lliçó 08-02 ensenya a mesurar de debò amb time, SECONDS i date +%s%N, a identificar el cost que domina en Bash —crear processos— i a optimitzar només allò que de veritat costa, començant per perfilar informe-diari.sh sobre mig milió de línies.