Amb la v0.21 el projecte està documentat, aguanta els errors, té historial i vuit proves que el verifiquen en centèsimes de segon. Falta l'últim, i és el que separa un programa que funciona d'un del qual un se sent orgullós: com està escrit. Perquè un programa s'escriu una vegada i es llegeix desenes: cada vegada que hi tornes, cada vegada que busques un error, cada vegada que algú nou entra al projecte. A TascaFàcil hi ha funcions a interficie.py que han crescut fins a les quaranta línies, el número 52 apareix solt en tres llocs, hi ha noms heretats de quan això era un exercici i blocs de codi que es repeteixen amb dues paraules canviades. Aquesta lliçó ho arregla tot: la guia d'estil oficial de Python, les eines que l'apliquen soles, l'art de posar bons noms, les olors de codi que delaten un problema i un catàleg de refactoritzacions que milloren el codi sense canviar el que fa —recolzant-te, precisament, en les proves que vas escriure a la lliçó anterior.

1. PEP 8: la guia d'estil de Python
2. Convencions de noms
3. El Zen de Python
4. Eines: formatadors i linters
5. Posar bons noms
6. Olors de codi
7. Què és refactoritzar (i què no)
8. Catàleg de refactoritzacions
9. TascaFàcil v1.0: revisat, formatat i refactoritzat
10. Errors habituals i consells
11. Exercicis
12. Conclusió

PEP 8 és el document oficial que defineix com s'escriu Python. No canvia el comportament de res: defineix l'aspecte, i el seu valor rau en el fet que tothom escriu igual, així que qualsevol codi Python et resulta familiar des del primer minut. Aquestes són les seves regles pràctiques:

Aquest ordre no és un caprici: en mirar la capçalera d'un fitxer saps d'un cop d'ull què depèn de fora i què és del projecte. I una nota important sobre la longitud de línia: el límit existeix per poder llegir dos fitxers en paral·lel i perquè el diff de Git sigui llegible, no per nostàlgia de les pantalles antigues.

El curs fa servir aquestes convencions des de Variables i tipus de dades; ara els posem el seu nom oficial:

El guió baix inicial mereix un aclariment, perquè a Python no impedeix res: agenda._tasques és perfectament accessible. És un acord entre programadors, no una barrera tècnica: significa «això és un detall intern, pot canviar demà i no hi hauries de dependre». Aquest acord és justament el que va permetre a 07-03 canviar per dins la llista d'Agenda sense trencar res a ningú.

Escriu import this a l'intèrpret i apareixeran dinou aforismes que resumeixen la filosofia del llenguatge. Aquests cinc són els que més et serviran:

• «Explicit is better than implicit» (explícit millor que implícit). Per això import format guanya a from format import *, i per això una funció que retorna Tasca | None ho diu a la seva signatura en lloc de deixar que ho descobreixis en fallar.
• «Simple is better than complex» (simple millor que complex). Una cerca lineal en una llista de 200 tasques és la solució correcta; l'índex i l'arbre binari són una complexitat que ningú no ha demanat.
• «Readability counts» (la llegibilitat compta). És la raó de ser d'aquesta lliçó sencera: entre dues solucions igual de vàlides, guanya la que es llegeix millor.
• «Errors should never pass silently» (els errors mai no haurien de passar en silenci). Exactament el que vam dir a 08-02 sobre except: pass.
• «There should be one obvious way to do it» (hi hauria d'haver una manera òbvia de fer-ho). Per això el projecte sencer fa servir un sol estil de docstring i una sola manera de validar.

No són regles obligatòries sinó criteris per desempatar. Quan dubtis entre dues maneres d'escriure alguna cosa, pregunta't quina de les dues és més explícita, més simple i més llegible; gairebé sempre és la mateixa.

El millor de tot l'anterior és que gairebé res d'això no s'ha de fer a mà. Hi ha dues famílies d'eines: els formatadors, que reescriuen el codi perquè compleixi l'estil, i els linters, que l'analitzen i avisen de problemes.

La diferència entre els dos tipus és important: black no opina sobre el teu codi, només sobre el seu aspecte; et treu per sempre les discussions sobre cometes, espais i salts de línia. ruff sí que opina: et dirà que has importat alguna cosa que no fas servir, que una variable està definida i mai no es llegeix o que una funció és massa complexa. A VS Code s'integren en dos clics: instal·la l'extensió de Python, tria black com a formatador i activa «Format on Save»; a partir d'aquí l'estil deixa de ser una preocupació teva.

És l'única cosa d'aquesta lliçó que cap eina no pot fer per tu, i probablement el que més influeix en la llegibilitat. Un bon nom diu què és o què fa, sense abreviatures críptiques ni informació redundant:

Tres criteris que ho resumeixen tot: els booleans comencen per un verb d'estat (esta_, hi_ha_, te_), les funcions comencen per un verb que diu què fan (cercar, desar, normalitzar) i les col·leccions van en plural (tasques, responsables). I si un nom necessita un comentari al costat per entendre's, el nom està malament.

Una olor de codi (code smell) no és un error: el programa funciona. És un senyal que alguna cosa donarà problemes aviat. Aquestes són les set que trobaràs una vegada i una altra:

L'últim és el més subtil i el més útil d'aprendre. Un comentari del tipus # aqui calculem el recarrec i apliquem el descompte està assenyalant, sense voler, que aquell bloc és una funció que encara no té nom. Extreu-lo i anomena'l aplicar_recarrec_i_descompte(): el comentari desapareix perquè ja no cal, i de passada el tros esdevé provable de manera aïllada.

Refactoritzar és canviar l'estructura interna del codi sense canviar en absolut el que fa. Aquesta segona part és la definició completa, i d'ella en surten dues conseqüències que convé tenir molt clares:

• No és refactoritzar afegir una funcionalitat, arreglar un error ni millorar el rendiment. Tot això canvia el comportament; refactoritzar, no.
• Mai no es fan les dues coses alhora. Si refactoritzes i afegeixes una funció al mateix commit i alguna cosa es trenca, no sabràs què ho ha trencat. Primer una cosa, després l'altra, cadascuna amb el seu commit (08-03).

I d'aquí en surt la regla d'or: abans de refactoritzar cal tenir proves. Les proves de 08-04 són les que responen a l'única pregunta que importa mentre reorganitzes el codi —«continua fent exactament el mateix?»— i les que converteixen l'operació en una cosa segura. El cicle és sempre aquest: proves en verd, un canvi petit, executar les proves, commit; i tornar a començar. Si en algun moment es posen en vermell, saps amb total certesa què ho ha provocat, perquè acabes de fer un sol canvi.

Aquestes sis resolen la immensa majoria dels casos. Extreure funció parteix un bloc llarg en peces amb nom:

Extreure variable explicativa converteix una expressió il·legible en una cosa que s'entén sola, i substituir el número màgic per una constant fa el mateix amb els valors solts:

Invertir la condició i fer servir una clàusula de guarda aplana la imbricació profunda, que és l'olor que més costa de llegir:

Unificar duplicats i substituir una cadena d'if per un diccionari de despatx tanquen el catàleg. La segona és especialment rendible als menús:

Fixa't en el que ha guanyat la segona versió: afegir una opció nova és una línia al diccionari en lloc de dues a la cadena, el conjunt d'opcions vàlides és en un únic lloc i ACCIONS.keys() serveix directament per validar l'entrada de l'usuari. És la mateixa idea de les funcions com a valors de 04-05, aplicada al problema real.

Primer, les eines, amb les proves en verd abans de començar:

ruff ha assenyalat exactament les dues funcions que sabíem que estaven malament: gestionar_opcio, amb la seva cadena de catorze elif, i mostrar_fitxa, amb el bloc de format. La primera s'arregla amb el diccionari de despatx i la segona extraient capcalera() i barra_progres(), tal com acabes de veure. Després de cada canvi, la comprovació que ho justifica tot:

Les vuit proves continuen en verd sense haver-ne tocat ni una, i això és la demostració que la refactorització va ser una refactorització de debò: el comportament és idèntic. El projecte arriba així a la v1.0, el número que segons el versionatge semàntic de 08-01 significa «això ja és estable». Mira d'on ve:

• Discutir sobre estil. És temps perdut: instal·la black, activa'l en desar i dedica aquesta energia al que sí que importa.
• Refactoritzar sense proves. És reescriure a cegues. Primer les proves en verd, després el canvi.
• Refactoritzar i canviar el comportament al mateix commit. Si alguna cosa es trenca, no sabràs què ha estat. Un commit, una intenció.
• La refactorització gegant. Canvis petits amb les proves executades entre l'un i l'altre; mai una reescriptura de tres dies.
• Confondre «curt» amb «llegible». Una línia de codi que s'ha de llegir tres vegades no és millor que tres línies clares.
• Fer cas cec al linter. Avisa, no mana. Si tens una raó per deixar alguna cosa com està, deixa-la (i anota el perquè en un comentari).
• Consell: aplica la regla del campament. Deixa cada fitxer que toques una mica millor que com el vas trobar: un nom, una constant, una funció extreta. En uns mesos el projecte sencer està net sense haver-te aturat mai a netejar-lo.

Reescriu aquest fragment aplicant PEP 8, les convencions de noms i les constants que calguin:

Enumera les olors de codi d'aquesta funció, digues quina refactorització correspon a cadascuna i reescriu-la:

Refactoritza aquesta funció fent servir una clàusula de guarda i un diccionari de despatx, i explica per què el resultat és més fàcil d'ampliar:

Solució 1.

Els canvis són set: indentació de 4 espais, un import per línia i en ordre alfabètic, nom de funció en snake_case i descriptiu (PROC no diu res i a més semblava una classe), variables amb nom complet, les claus 'p' i 'd' llegibles, els números màgics convertits en constants i l'if d'una línia desplegat. Ah, i el paràmetre f no es feia servir: ruff ho hauria detectat a l'acte.

Solució 2.

Hi ha tres olors: codi duplicat (el bucle es repeteix tres vegades idèntic), una cadena d'if sobre un valor (candidata a diccionari de despatx) i cadenes màgiques ("curt", "llarg", "csv" soltes). La refactorització que correspon és extreure el format d'una línia a funcions i despatxar per diccionari:

El bucle apareix una sola vegada i l'única cosa que varia —el format de la línia— viu al diccionari. Afegir un format nou és ara una línia, els formats vàlids són en un únic lloc i el missatge d'error els enumera sol. És exactament la idea de les funcions com a valors de 04-05 posada a treballar.

Solució 3.

La clàusula de guarda descarta al principi els casos en què no hi ha res a fer, i el cos real de la funció queda sense imbricació: es llegeix de dalt a baix sense sostenir condicions al cap. I ampliar és trivial: una acció nova és una entrada a ACCIONS, sense tocar la funció. En un projecte real convé anar un pas més enllà i substituir aquestes lambda amb setattr per mètodes de Tasca (posposar(), marcar_urgent()), perquè el comportament d'una tasca pertany a la classe Tasca: és la lliçó de 07-02 aplicada aquí.

El codi es llegeix moltes més vegades de les que s'escriu, i per això l'estil no és cosmètica. PEP 8 fixa el bàsic —4 espais d'indentació, línies de menys de 79 (o 88) caràcters, línies en blanc que separen idees, espais al voltant dels operadors i imports ordenats en estàndard, tercers i propis— i les convencions de noms posen nom oficial al que el curs venia fent des de 02-01: snake_case per a variables i funcions, PascalCase per a classes, MAJUSCULES per a constants i _privat com a acord entre programadors que Python no imposa. El Zen de Python (import this) aporta els criteris per desempatar: explícit millor que implícit, simple millor que complex, la llegibilitat compta, els errors mai no haurien de passar en silenci i hi hauria d'haver una manera òbvia de fer les coses. Gairebé tot això ho apliquen soles les eines: black reformata sense discussió, ruff, flake8 i pylint detecten problemes, mypy comprova les anotacions de 08-01, i VS Code ho executa en desar. L'única cosa que no es pot automatitzar són els noms: verbs per a les funcions, plural per a les col·leccions, esta_/hi_ha_ per als booleans i mai una abreviatura que necessiti un comentari. Les olors de codi —funció massa llarga, massa paràmetres, duplicació, números i cadenes màgics, imbricació profunda, noms críptics i el comentari que explica un tram confús— assenyalen on actuar. I refactoritzar és millorar l'estructura sense canviar el comportament, mai barrejat amb una altra cosa al mateix commit i sempre amb proves en verd abans de començar: extreure funció, extreure variable explicativa, substituir número màgic per constant, invertir la condició amb una clàusula de guarda, unificar duplicats i substituir la cadena d'if per un diccionari de despatx.

TascaFàcil és la v1.0: formatat amb black, revisat amb ruff, amb interficie.py refactoritzada i amb les mateixes vuit proves en verd, que és la prova que res no va canviar per fora. I amb això es tanca el mòdul 8 i, de fet, tot el recorregut tècnic del curs. Vas començar sense saber què era una variable i ara tens el llenguatge (tipus, operadors, entrada i sortida), les estructures de control, les funcions, les estructures de dades amb la seva persistència en fitxers, els algorismes de cerca i ordenació amb el seu cost, la programació orientada a objectes amb mòduls i paquets, i les cinc eines professionals d'aquest mòdul: documentació, depuració i gestió d'errors, control de versions, proves automatitzades i refactorització. Això és exactament l'equipatge amb què treballa un programador.

Només queda una cosa per fer, i és la més important de totes: construir alguna cosa sencera des de zero, tu sol. Fins ara cada peça de TascaFàcil venia proposada; al mòdul 9 el projecte el tries tu, el dissenyes, el planifiques, l'implementes, el proves i el presentes. Comencem a Definició del projecte, decidint què val la pena construir i —tan important com això— on posar el límit per acabar-lo.