Con la v0.21 el proyecto está documentado, aguanta los errores, tiene historial y ocho pruebas que lo verifican en centésimas de segundo. Falta lo último, y es lo que separa un programa que funciona de uno del que uno se enorgullece: cómo está escrito. Porque un programa se escribe una vez y se lee decenas: cada vez que vuelves a tocarlo, cada vez que buscas un fallo, cada vez que alguien nuevo entra en el proyecto. En TareaFácil hay funciones en interfaz.py que han crecido hasta las cuarenta líneas, el número 52 aparece suelto en tres sitios, hay nombres heredados de cuando esto era un ejercicio y bloques de código que se repiten con dos palabras cambiadas. Esta lección arregla todo eso: la guía de estilo oficial de Python, las herramientas que la aplican solas, el arte de poner buenos nombres, los olores de código que delatan un problema y un catálogo de refactorizaciones que mejoran el código sin cambiar lo que hace —apoyándote, precisamente, en las pruebas que escribiste en la lección anterior.

1. PEP 8: la guía de estilo de Python
2. Convenciones de nombres
3. El Zen de Python
4. Herramientas: formateadores y linters
5. Poner buenos nombres
6. Olores de código
7. Qué es refactorizar (y qué no)
8. Catálogo de refactorizaciones
9. TareaFácil v1.0: revisado, formateado y refactorizado
10. Errores comunes y consejos
11. Ejercicios
12. Conclusión

PEP 8 es el documento oficial que define cómo se escribe Python. No cambia el comportamiento de nada: define el aspecto, y su valor está en que todo el mundo escribe igual, así que cualquier código Python te resulta familiar desde el primer minuto. Estas son sus reglas prácticas:

Ese orden no es capricho: al mirar la cabecera de un fichero sabes de un vistazo qué depende de fuera y qué es del proyecto. Y una nota importante sobre la longitud de línea: el límite existe para poder leer dos ficheros en paralelo y para que el diff de Git sea legible, no por nostalgia de las pantallas antiguas.

El curso lleva usando estas convenciones desde Variables y tipos de datos; ahora les ponemos su nombre oficial:

El guion bajo inicial merece una aclaración, porque en Python no impide nada: agenda._tareas es perfectamente accesible. Es un acuerdo entre programadores, no una barrera técnica: significa «esto es un detalle interno, puede cambiar mañana y no deberías depender de ello». Ese acuerdo es justo lo que permitió en 07-03 cambiar por dentro la lista de Agenda sin romper a nadie.

Escribe import this en el intérprete y aparecerán diecinueve aforismos que resumen la filosofía del lenguaje. Estos cinco son los que más te van a servir:

• «Explicit is better than implicit» (explícito mejor que implícito). Por eso import formato gana a from formato import *, y por eso una función que devuelve Tarea | None lo dice en su firma en lugar de dejar que lo descubras al fallar.
• «Simple is better than complex» (simple mejor que complejo). Una búsqueda lineal en una lista de 200 tareas es la solución correcta; el índice y el árbol binario son una complejidad que nadie ha pedido.
• «Readability counts» (la legibilidad cuenta). Es la razón de ser de esta lección entera: entre dos soluciones igual de válidas, gana la que se lee mejor.
• «Errors should never pass silently» (los errores nunca deberían pasar en silencio). Exactamente lo que dijimos en 08-02 sobre except: pass.
• «There should be one obvious way to do it» (debería haber una forma obvia de hacerlo). Por eso el proyecto entero usa un solo estilo de docstring y una sola forma de validar.

No son reglas obligatorias sino criterios para desempatar. Cuando dudes entre dos formas de escribir algo, pregúntate cuál de las dos es más explícita, más simple y más legible; casi siempre es la misma.

Lo mejor de todo lo anterior es que casi nada de eso hay que hacerlo a mano. Hay dos familias de herramientas: los formateadores, que reescriben el código para que cumpla el estilo, y los linters, que lo analizan y avisan de problemas.

La diferencia entre los dos tipos es importante: black no opina sobre tu código, solo sobre su aspecto; te quita para siempre las discusiones sobre comillas, espacios y saltos de línea. ruff sí opina: te dirá que has importado algo que no usas, que una variable está definida y nunca se lee o que una función es demasiado compleja. En VS Code se integran en dos clics: instala la extensión de Python, elige black como formateador y activa «Format on Save»; a partir de ahí el estilo deja de ser una preocupación tuya.

Es lo único de esta lección que ninguna herramienta puede hacer por ti, y probablemente lo que más influye en la legibilidad. Un buen nombre dice qué es o qué hace, sin abreviaturas crípticas ni información redundante:

Tres criterios que resumen todo: los booleanos empiezan por un verbo de estado (esta_, hay_, tiene_), las funciones empiezan por un verbo que dice qué hacen (buscar, guardar, normalizar) y las colecciones van en plural (tareas, responsables). Y si un nombre necesita un comentario al lado para entenderse, el nombre está mal.

Un olor de código (code smell) no es un error: el programa funciona. Es una señal de que algo va a dar problemas pronto. Estos son los siete que encontrarás una y otra vez:

El último es el más sutil y el más útil de aprender. Un comentario del tipo # aqui calculamos el recargo y aplicamos el descuento está señalando, sin querer, que ese bloque es una función que todavía no tiene nombre. Extráelo y llámalo aplicar_recargo_y_descuento(): el comentario desaparece porque ya no hace falta, y de paso el trozo se vuelve probable de forma aislada.

Refactorizar es cambiar la estructura interna del código sin cambiar en absoluto lo que hace. Esa segunda parte es la definición completa, y de ella salen dos consecuencias que conviene tener muy claras:

• No es refactorizar añadir una funcionalidad, arreglar un fallo ni mejorar el rendimiento. Todo eso cambia el comportamiento; refactorizar, no.
• Nunca se hacen las dos cosas a la vez. Si refactorizas y añades una función en el mismo commit y algo se rompe, no sabrás qué lo rompió. Primero una cosa, después la otra, cada una con su commit (08-03).

Y de ahí sale la regla de oro: antes de refactorizar hay que tener pruebas. Las pruebas de 08-04 son las que responden a la única pregunta que importa mientras reorganizas el código —«¿sigue haciendo exactamente lo mismo?»— y las que convierten la operación en algo seguro. El ciclo es siempre este: pruebas en verde, un cambio pequeño, ejecutar las pruebas, commit; y vuelta a empezar. Si en algún momento se ponen en rojo, sabes con total certeza qué lo ha provocado, porque acabas de hacer un solo cambio.

Estas seis resuelven la inmensa mayoría de los casos. Extraer función parte un bloque largo en piezas con nombre:

Extraer variable explicativa convierte una expresión ilegible en algo que se entiende solo, y sustituir el número mágico por una constante hace lo mismo con los valores sueltos:

Invertir la condición y usar una cláusula de guarda aplana el anidamiento profundo, que es el olor que más cuesta leer:

Unificar duplicados y sustituir una cadena de if por un diccionario de despacho cierran el catálogo. Lo segundo es especialmente rentable en los menús:

Fíjate en lo que ha ganado la segunda versión: añadir una opción nueva es una línea en el diccionario en lugar de dos en la cadena, el conjunto de opciones válidas está en un único sitio y ACCIONES.keys() sirve directamente para validar la entrada del usuario. Es la misma idea de las funciones como valores de 04-05, aplicada al problema real.

Primero, las herramientas, con las pruebas en verde antes de empezar:

ruff ha señalado exactamente las dos funciones que sabíamos que estaban mal: gestionar_opcion, con su cadena de catorce elif, y mostrar_ficha, con el bloque de formato. La primera se arregla con el diccionario de despacho y la segunda extrayendo cabecera() y barra_progreso(), tal y como acabas de ver. Después de cada cambio, la comprobación que lo justifica todo:

Las ocho pruebas siguen en verde sin haber tocado una sola de ellas, y eso es la demostración de que la refactorización fue una refactorización de verdad: el comportamiento es idéntico. El proyecto llega así a la v1.0, el número que según el versionado semántico de 08-01 significa «esto ya es estable». Mira de dónde viene:

• Discutir sobre estilo. Es tiempo perdido: instala black, actívalo al guardar y dedica esa energía a lo que sí importa.
• Refactorizar sin pruebas. Es reescribir a ciegas. Primero las pruebas en verde, después el cambio.
• Refactorizar y cambiar el comportamiento en el mismo commit. Si algo se rompe, no sabrás qué fue. Un commit, una intención.
• La refactorización gigante. Cambios pequeños con las pruebas ejecutadas entre uno y otro; nunca una reescritura de tres días.
• Confundir «corto» con «legible». Una línea de código que hay que leer tres veces no es mejor que tres líneas claras.
• Hacer caso ciego al linter. Avisa, no manda. Si tienes una razón para dejar algo como está, déjalo (y anota el porqué en un comentario).
• Consejo: aplica la regla del campamento. Deja cada fichero que tocas un poco mejor que como lo encontraste: un nombre, una constante, una función extraída. En unos meses el proyecto entero está limpio sin haber parado nunca a limpiarlo.

Reescribe este fragmento aplicando PEP 8, las convenciones de nombres y las constantes que hagan falta:

Enumera los olores de código de esta función, di qué refactorización corresponde a cada uno y reescríbela:

Refactoriza esta función usando una cláusula de guarda y un diccionario de despacho, y explica por qué el resultado es más fácil de ampliar:

Solución 1.

Los cambios son siete: indentación de 4 espacios, un import por línea y en orden alfabético, nombre de función en snake_case y descriptivo (PROC no dice nada y además parecía una clase), variables con nombre completo, las claves 'p' y 'd' legibles, los números mágicos convertidos en constantes y el if de una línea desplegado. Ah, y el parámetro f no se usaba: ruff lo habría detectado en el acto.

Solución 2.

Hay tres olores: código duplicado (el bucle se repite tres veces idéntico), una cadena de if sobre un valor (candidata a diccionario de despacho) y cadenas mágicas ("corto", "largo", "csv" sueltas). La refactorización que corresponde es extraer el formato de una línea a funciones y despachar por diccionario:

El bucle aparece una sola vez y lo único que varía —el formato de la línea— vive en el diccionario. Añadir un formato nuevo es ahora una línea, los formatos válidos están en un único sitio y el mensaje de error los enumera solo. Es exactamente la idea de las funciones como valores de 04-05 puesta a trabajar.

Solución 3.

La cláusula de guarda descarta al principio los casos en los que no hay nada que hacer, y el cuerpo real de la función queda sin anidamiento: se lee de arriba abajo sin sostener condiciones en la cabeza. Y ampliar es trivial: una acción nueva es una entrada en ACCIONES, sin tocar la función. En un proyecto real conviene ir un paso más allá y sustituir esas lambda con setattr por métodos de Tarea (posponer(), marcar_urgente()), porque el comportamiento de una tarea pertenece a la clase Tarea: es la lección de 07-02 aplicada aquí.

El código se lee muchas más veces de las que se escribe, y por eso el estilo no es cosmética. PEP 8 fija lo básico —4 espacios de indentación, líneas de menos de 79 (u 88) caracteres, líneas en blanco que separan ideas, espacios alrededor de los operadores e imports ordenados en estándar, terceros y propios— y las convenciones de nombres ponen nombre oficial a lo que el curso venía haciendo desde 02-01: snake_case para variables y funciones, PascalCase para clases, MAYUSCULAS para constantes y _privado como acuerdo entre programadores que Python no impone. El Zen de Python (import this) aporta los criterios para desempatar: explícito mejor que implícito, simple mejor que complejo, la legibilidad cuenta, los errores nunca deberían pasar en silencio y debería haber una forma obvia de hacer las cosas. Casi todo eso lo aplican solas las herramientas: black reformatea sin discusión, ruff, flake8 y pylint detectan problemas, mypy comprueba las anotaciones de 08-01, y VS Code lo ejecuta al guardar. Lo único que no puede automatizarse son los nombres: verbos para las funciones, plural para las colecciones, esta_/hay_ para los booleanos y nunca una abreviatura que necesite un comentario. Los olores de código —función demasiado larga, demasiados parámetros, duplicación, números y cadenas mágicos, anidamiento profundo, nombres crípticos y el comentario que explica un tramo confuso— señalan dónde actuar. Y refactorizar es mejorar la estructura sin cambiar el comportamiento, jamás mezclado con otra cosa en el mismo commit y siempre con pruebas en verde antes de empezar: extraer función, extraer variable explicativa, sustituir número mágico por constante, invertir la condición con una cláusula de guarda, unificar duplicados y sustituir la cadena de if por un diccionario de despacho.

TareaFácil es la v1.0: formateado con black, revisado con ruff, con interfaz.py refactorizada y con las mismas ocho pruebas en verde, que es la prueba de que nada cambió por fuera. Y con esto se cierra el módulo 8 y, de hecho, todo el recorrido técnico del curso. Empezaste sin saber qué era una variable y ahora tienes el lenguaje (tipos, operadores, entrada y salida), las estructuras de control, las funciones, las estructuras de datos con su persistencia en ficheros, los algoritmos de búsqueda y ordenación con su coste, la programación orientada a objetos con módulos y paquetes, y las cinco herramientas profesionales de este módulo: documentación, depuración y manejo de errores, control de versiones, pruebas automatizadas y refactorización. Eso es exactamente el equipaje con el que trabaja un programador.

Solo queda una cosa por hacer, y es la más importante de todas: construir algo entero desde cero, tú solo. Hasta ahora cada pieza de TareaFácil venía propuesta; en el módulo 9 el proyecto lo eliges, lo diseñas, lo planificas, lo implementas, lo pruebas y lo presentas. Empezamos en Definición del proyecto, decidiendo qué merece la pena construir y —tan importante como eso— dónde poner el límite para terminarlo.