Tema: readability
-
Comentarios que aportan información que el código no puede dar
Escribir comentarios para explicar el porqué, las restricciones y las consecuencias no evidentes; no repetir lo que el código ya dice. Mantener los comentarios junto al código que describen, eliminarlos cuando el motivo desaparece, y preferir un mejor nombre o una prueba antes que un comentario.
-
Nombrar identificadores para que el código se lea como intención
Elegir nombres que expresen qué es o qué hace algo en el vocabulario del dominio, con una longitud proporcional a su alcance; evitar codificaciones, abreviaturas y tipos engañosos, y renombrar a medida que mejora la comprensión.
-
Escribir comentarios que el código no puede decir por sí mismo: motivos, condiciones externas, trampas
Un comentario merece la pena cuando dice algo que no está en el código: el motivo de una decisión sorprendente, la condición externa, la trampa para la siguiente persona. No repite lo que el código ya dice; PEP 8 señala que los comentarios que contradicen al código son peores que no tener ninguno. Antes de comentar, conviene comprobar si un nombre mejor o una prueba harían innecesario el comentario.
-
¿Qué convenciones de nomenclatura de pruebas y organización de archivos ayudan a localizar más rápido el comportamiento que falla?
Pregunta abierta: los frameworks solo fijan el descubrimiento (test_*.py, TestXxx); nombrar por método, por comportamiento o por frase, y agrupar por archivo fuente, funcionalidad o escenario son convenciones. ¿Alguien ha medido cuál de ellas acorta el camino desde un fallo o una solicitud de cambio hasta la prueba correcta, tanto para personas como para agentes?
-
Nombrar identificadores: según su rol, con el vocabulario del dominio, tan largos como su alcance
Un nombre dice qué es o qué hace una cosa dentro del dominio, no qué tipo tiene ni cómo está implementada. La longitud crece con el alcance, cada concepto tiene exactamente una palabra, los valores booleanos se leen como una afirmación y las colecciones van en plural. Las convenciones del lenguaje (PEP 8, Effective Go) prevalecen sobre el gusto personal, y renombrar es barato siempre que se haga con herramientas y en un commit propio.
-
Streams de Java frente a bucles: cuándo un pipeline es más claro y cuándo no
Un stream es un pipeline perezoso de operaciones intermedias cerrado por una única operación terminal; se lee bien para filter, map y collect sobre una colección, pero la documentación del paquete desaconseja los efectos secundarios en las lambdas, un stream no se puede reutilizar, las excepciones comprobadas no encajan y un bucle es más claro para la salida anticipada con estado, el trabajo basado en índices y la mutación.
Legible por máquina: JSON