English

Documenta las trampas inline, donde muerden

¿El bug que te costó un día? Escribe la advertencia justo donde la próxima persona va a caer. Una página de wiki que nadie abre no detiene la próxima trampa — el archivo de código es el único documento que cada futuro lector tendrá abierto, garantizado, en el momento exacto en que está por repetir tu error. Y eso ahora incluye a tu asistente de IA, que lee el archivo que le indicas, no la base de conocimiento de tu equipo.

Por qué la wiki pierde

Una trampa es conocimiento con ubicación. "Este endpoint trunca silenciosamente payloads de más de 1 MB" es inútil en una página de Confluence titulada API Notes y vale oro como comentario sobre la función que arma el payload. La regla de Jeff Atwood sigue vigente dos décadas después: el código solo puede decirte cómo funciona el programa; los comentarios te dicen por qué. El límite de truncado se ve en el código — el hecho de que una vez costó un día de debugging en producción, no.

El costo de descubrimiento lo decide todo. Una advertencia en la wiki exige que el lector (1) sepa que la página existe, (2) sospeche que esta función es la riesgosa y (3) vaya a buscarla — tres pasos que fallan en silencio. Un comentario inline exige cero pasos: aparece en el diff, en el editor, en la salida de grep y en la ventana de contexto.

Cómo escribir la advertencia

Pon el comentario sobre el símbolo riesgoso, no al inicio del archivo, y haz que cargue tres cosas:

# IMPORTANT: send_batch() silently drops events after the first
# failure in a batch (upstream API returns 200 either way).
# Why: the vendor treats a batch as best-effort delivery.
# If you need all-or-nothing, call send_single() in a loop —
# yes it's slower; we lost a day of analytics data learning this.
def send_batch(events: list[Event]) -> None:
    ...

La anatomía:

La guía de estilo de Python de Google lo dice sin rodeos: "si vas a tener que explicarlo en el próximo code review, deberías comentarlo ahora". Y el principio "leave a trace for the reader" de su guía de C++ dice lo mismo — cuando pasa algo sorprendente, deja pistas textuales en el punto de uso.

Lo que no hay que escribir: comentarios que repiten el código. La primera regla del blog de ingeniería de Stack Overflow es "no dupliques el código" — un comentario de trampa se gana sus líneas justamente porque dice algo que el código no puede decir.

Tu agente también los lee

Esta es la parte que cambió la economía del asunto. Las advertencias inline antes protegían solo a los humanos que leían con cuidado. Ahora cada agente de código que carga el archivo recibe la advertencia inyectada directo en su contexto — gratis, en el momento en que importa. La guía de Claude Code de Anthropic lista explícitamente "gotchas comunes o comportamientos no obvios" como contenido que vale la pena persistir para el agente, y señala que marcadores de énfasis como IMPORTANT mejoran de forma medible la adherencia. El mismo prefijo # IMPORTANT: que atrapa el ojo humano en un review es una señal que el modelo pondera antes de llamar a tu función con trampa.

La recompensa es simétrica: el próximo ingeniero y el próximo agente esquivan la trampa, en lugar de que tu equipo pague dos veces por el mismo bug.

Movidas de usuario avanzado

• Comenta al momento del fix, en el commit del fix. El instante en que cierras la investigación es el único en que tienes el "por qué" completo en la cabeza. Las guías de Stack Overflow lo dicen directo: comenta tus correcciones de bugs.
• Haz las trampas buscables con grep. Elige un prefijo (IMPORTANT:, GOTCHA:, SAFETY:) y úsalo con consistencia — así grep -rn "GOTCHA:" se vuelve un mapa de trampas gratis y siempre actualizado del código, para onboarding de humanos y para prompts de agentes por igual.
• Escala las reincidentes. Si la misma advertencia aplica a muchos archivos (una rareza del build, una variable de entorno obligatoria), promuévela de comentarios inline al archivo de instrucciones del agente (CLAUDE.md o equivalente) para que cargue en cada sesión — inline para trampas locales, archivo de proyecto para las globales.
• Enlaza el ensayo, no lo pegues. Cuando la historia completa del incidente importa, deja la advertencia de dos líneas inline y ciérrala con un enlace al ADR o al postmortem. El comentario es el cable trampa; el documento es la profundidad.

Recursos

• Code Tells You How, Comments Tell You Why — Jeff Atwood
• Best practices for writing code comments — blog de Stack Overflow
• Google Python Style Guide §3.8 — Comments and Docstrings
• Google C++ Style Guide — Comments ("leave a trace for the reader")
• Buenas prácticas de Claude Code — qué va en CLAUDE.md

Read this article in English