El día que dejé de comentar mi código y empecé a escribirlo como si fuera una carta

Este artículo puede incluir enlaces de afiliado. Si compras a través de ellos, me llevo una pequeña comisión sin coste extra para ti. Más información.

Hubo un momento concreto, hace cosa de tres años, en que miré un método que acababa de escribir y pensé: esto no lo entendería ni yo dentro de seis meses. El método hacía algo con fechas, tenía cinco comentarios explicando qué demonios hacía cada línea, y el nombre era processData(). Clásico. Llevaba años programando así y nunca me había parecido un problema. Entonces empecé a escribir mi segundo libro, y algo cambió.

Lo que escribir libros te enseña sobre tener lector

Cuando escribes un libro, aunque sea sobre gatos callejeros de Zaragoza, aprendes muy rápido que hay alguien al otro lado. Alguien que no estuvo cuando tú pensabas el capítulo, que no conoce tus intenciones, que solo tiene las palabras que pusiste en la página. Si esas palabras no son claras, el libro no funciona. No hay comentario al margen que salve una frase mal construida.

En programación, durante años, asumí que los comentarios eran ese margen. Que podía escribir código opaco y luego explicarlo encima, como un subtítulo. Lo que no había pensado es que un subtítulo que tiene que existir ya es señal de que algo en la imagen no funciona.

La primera vez que lo vi claro fue revisando un capítulo del libro donde describía cómo un gato viejo llamado Tronco se acercaba a los desconocidos. Tenía escrito: «Tronco se aproximaba. Era curioso, aunque desconfiado.» Mi editora lo subrayó y escribió al lado: «muéstralo, no lo digas.» Eso me golpeó. Y dos días después, mirando un método llamado checkUserStatus() con un comentario que decía // verifica si el usuario está activo y tiene permisos, me pregunté: ¿por qué no se llama isActiveWithPermissions()?

El nombre lo es casi todo

Nombrar bien es el trabajo más difícil y el más ignorado. En escritura lo sabemos: una novela puede sostenerse o derrumbarse por el nombre de su protagonista. En código pasa igual, pero lo tratamos como si fuera un trámite.

Yo era de los que usaba data, result, temp, obj. Variables que no dicen nada. Variables que son como llamar a todos los personajes de tu novela «Chico» y «Chica» y esperar que el lector lo descifre por contexto.

Ahora me hago una pregunta antes de nombrar cualquier cosa: ¿si alguien lee esto sin saber nada del contexto, entiende qué es? No siempre lo consigo. Pero la pregunta ya cambia cómo pienso.

Un caso concreto: tenía un booleano que controlaba si había que enviar un correo de confirmación cuando se completaba un pedido. Lo tenía como flag. Después lo cambié a shouldSendOrderConfirmation. Tardé cuatro segundos en escribirlo. Y la siguiente vez que alguien tocó ese código, que fui yo mismo tres meses después, no tuve que leer nada más para saber qué hacía.

Los métodos como párrafos, no como cajones

Otra cosa que aprendí escribiendo: un párrafo tiene que tener una sola idea. Si empieza hablando de la textura del asfalto en invierno y acaba en la filosofía estoica, algo ha fallado. Puede haber un hilo que los conecte, pero la unidad tiene que estar ahí.

Mis métodos eran cajones. Metía todo lo que tenía relación vagamente con el tema del método. processOrder() validaba, calculaba impuestos, actualizaba inventario, enviaba emails y a veces hacía logging. Todo en uno. Doscientas líneas. Un cajón donde habías metido la ropa de invierno, el pasaporte y tres cables de móvil que ya no sabes de qué son.

Un método, una responsabilidad

Esto no es nuevo. Es el principio de responsabilidad única, que existe en los libros de programación desde hace décadas. Pero a mí no me entró de verdad hasta que lo conecté con escribir. Cuando fragmenté processOrder() en validateOrderData(), calculateTaxes(), updateInventory() y sendConfirmationEmail(), el código se volvió legible de una manera que me sorprendió. Podías leer el método principal como si fuera el índice de un libro. Sabías exactamente qué iba a pasar y en qué orden.

El flujo como narración

Hay algo que los escritores llaman ritmo. No es solo la longitud de las frases, es también el orden en que ocurren las cosas. Lo mismo pasa en el código. Un método que valida al principio, luego transforma, luego guarda y luego notifica tiene un ritmo. Uno que mezcla esas fases al azar es difícil de seguir, aunque técnicamente funcione.

Empecé a pensar en el flujo de mis métodos como en la estructura de una escena. Primero estableces el contexto, luego ocurre algo, luego hay una consecuencia. No siempre es tan limpio, pero tenerlo como norte ayuda más de lo que esperaba.

Cuándo un comentario sí tiene sentido

No soy de los que dicen que los comentarios son el mal. Hay casos donde son necesarios, y negarlos sería una postura bonita pero poco práctica.

Los comentarios tienen sentido cuando explican el porqué, no el qué. Si hay una decisión de negocio rara, una limitación de una API externa, un bug histórico que obligó a hacer algo poco intuitivo: eso merece un comentario. Lo que no lo merece es explicar que un bucle for itera sobre una lista. Eso lo ve cualquiera.

La prueba que uso ahora: si el comentario desapareciera, ¿el código seguiría siendo comprensible? Si la respuesta es sí, el comentario probablemente sobra. Si la respuesta es no, o hay que mejorar el código, o el comentario está justificado porque explica algo que el código por sí solo no puede expresar.

Es una distinción que en escritura también existe. Las notas al pie de página tienen mala fama, pero las buenas notas al pie añaden algo que no cabía en el texto sin romper el ritmo. Las malas notas al pie son un síntoma de que el texto no funcionaba solo.

La persona que leerá esto no eres tú

Esta es, creo, la idea central de todo. Cuando escribo un capítulo, no escribo para mí. Escribo para alguien que no ha vivido lo que yo viví, que no tiene mis referencias, que va a leer esto en el metro o un domingo por la tarde sin saber nada de mí. Tengo que darle todo lo necesario para que entienda.

En el código pasa algo parecido, con un matiz: ese lector futuro muchas veces eres tú mismo. Tú dentro de seis meses, con otros problemas en la cabeza, sin recuerdo de por qué tomaste aquella decisión. Y mereces que tu yo del pasado te haya tratado bien.

Desde que empecé a pensar así, escribo código de otra manera. No perfecto, no siempre. Hay días de prisa y hay código feo que sale porque toca. Pero el hábito está. La pregunta está. ¿Quién va a leer esto? Y luego: ¿lo estoy tratando bien?

No sé si soy mejor programador que hace tres años. Probablemente en algunas cosas sí y en otras no. Pero sí sé que cuando abro código que escribí el año pasado, me reconozco en él. Y eso, para alguien que trabaja en proyectos que duran años, no es poca cosa.