English

Comenta el porqué, nunca el qué

Borra el noventa por ciento de tus comentarios. Conserva un solo tipo. La mayoría de los comentarios en una base de código típica repiten lo que la línea de abajo ya dice — y un comentario que repite el código se pudre en el momento en que esa línea cambia. El único tipo que vale la pena conservar registra algo que el código no puede decir: por qué existe.

El comentario que miente

PEP 8 usa el ejemplo canónico como su propio "no hagas esto":

x = x + 1                 # Increment x

Ese comentario no aporta ninguna información hoy, y peor: es una mentira en espera. Cambia la línea a x = x + step y el comentario ya es falso — y nadie actualiza los comentarios como actualiza el código. El contraejemplo de PEP 8 es la solución: x = x + 1 # Compensate for border. La misma línea, pero ahora el comentario aporta contexto que el código no puede expresar.

El blog de ingeniería de Stack Overflow lo pone como regla número uno para comentarios de código: los comentarios no deben duplicar el código. Los comentarios redundantes ensucian el archivo, cuestan tiempo de mantenimiento y quedan desactualizados. Refactoring.guru va más allá y clasifica los comentarios explicativos como un code smell en la categoría "Dispensables" — casi siempre una señal de que el código necesita renombrarse o extraerse, no anotarse.

Qué vs. porqué, en una línea

# QUÉ (bórralo — el código ya lo dice):
window.clear()  # clear the window

# PORQUÉ (consérvalo — el código no puede decirlo):
window.clear()  # reset the counter on a sliding window
                # to stop burst attacks at the window edge

El primer comentario repite el nombre del método. El segundo registra una decisión: alguien eligió una ventana deslizante en lugar de una fija, para un modelo de amenaza específico. Refactoriza la implementación — renombra el método, cambia la estructura de datos — y el comentario de porqué sigue siendo cierto, porque la intención no cambia cuando el código cambia.

Reglas prácticas

Si te cuesta escribir un comentario claro, suele ser señal de que el código necesita trabajo — extrae una función con buen nombre en lugar de anotar un bloque confuso.

Los comentarios de porqué son combustible para asistentes de IA

Aquí está el beneficio moderno. Los asistentes de programación con IA leen tus comentarios como parte de su contexto — y los ponderan como declaraciones de intención. Un comentario de qué no le da al modelo nada que no haya extraído ya del código. Un comentario de porqué hace dos cosas:

• Detiene la re-discusión. "Sliding window to stop burst attacks at the window edge" le dice al asistente que fue una elección deliberada. Sin eso, un agente al que le pidas "limpiar" el rate limiter puede simplificarlo amablemente a una ventana fija — deshaciendo una decisión que nadie dejó escrita.
• Transfiere restricciones. "Don't parallelize — the API rate-limits per connection" evita que tanto tus colegas como tu agente de código cometan el mismo error tentador.

La forma más barata de alinear un asistente de IA con las decisiones de tu base de código es haberlas dejado escritas donde aplican — en línea, como comentarios de porqué.

Trucos avanzados

• Comenta la alternativa rechazada. El comentario de mayor valor suele ser "probamos X; falló por Y". Le ahorra a la próxima persona (o agente) todo un desvío.
• Enlaza, no parafrasees. ¿Copiaste un snippet o rodeaste un bug de una librería? Pon la URL en el comentario. Una fuente vale más que un resumen y se puede re-verificar después.
• Audita con un grep. Busca comentarios cuyas palabras aparecen en la línea de abajo (increment, set, return, loop over) — esos son comentarios de qué y borrarlos en review es casi gratis.
• Escala los porqués grandes a ADRs. Cuando el "porqué" abarca un módulo y no una línea, pertenece a un architecture decision record — el mismo principio, a mayor escala.

Recursos

• PEP 8 — Inline comments (el ejemplo "Increment x")
• Best practices for writing code comments — Stack Overflow Blog
• Code Tells You How, Comments Tell You Why — Coding Horror
• Comments como code smell — Refactoring.Guru

Read this article in English