Cómo gestionar comentarios TODO acumulados por cinco años

Los repositorios de software suelen parecerse a sitios arqueológicos. Dentro de las capas de lanzamientos de funciones y parches de emergencia, encontrarás miles de líneas que comienzan con la palabra TODO. Es común encontrar bases de código donde la tarea de gestionar comentarios TODO acumulados por cinco años se convierte en el principal obstáculo para la mantenibilidad a largo plazo. Estos comentarios representan decisiones postergadas, optimizaciones olvidadas y advertencias de desarrolladores del pasado que nunca llegaron al gestor de tareas. Abordar este volumen de deuda técnica de forma manual es un ejercicio inútil. Se requiere una receta estructurada para categorizar, priorizar y resolver estos fragmentos sin perder semanas de tiempo de ingeniería en cambios de contexto.

La taxonomía de los comentarios obsoletos

No todos los comentarios TODO se crean de la misma manera. Después de media década de desarrollo, un repositorio suele contener tres tipos distintos de deuda técnica ocultos a plena vista. Comprender estas categorías es el primer paso hacia un proceso de triaje exitoso.

La primera categoría consiste en detalles de implementación específicos. Se trata de tareas pequeñas, como reemplazar un simulacro (mock) temporal con una llamada a un servicio real o refactorizar una función única para mejorar la legibilidad. Estos son los más fáciles de resolver, pero también los más numerosos.

La segunda categoría involucra advertencias arquitectónicas. Estos comentarios a menudo comienzan con "arreglar esto más tarde" y apuntan a problemas estructurales profundos, como dependencias circulares o flujos de datos ineficientes. Estos no pueden resolverse en un solo commit y requieren ser mapeados en una hoja de ruta formal del proyecto.

La tercera categoría es lo que llamamos deuda fantasma. Son los TODOs que se refieren a funciones que ya no existen o a requisitos que han sido completamente superados. Estos deben eliminarse de inmediato para reducir la carga cognitiva del equipo.

Una receta para el triaje de deuda

Para manejar miles de líneas de código de manera efectiva, debes alejarte de la búsqueda global estándar del IDE. Necesitas un enfoque sistemático para filtrar el ruido.

1. Extracción: Utiliza grep o ripgrep para exportar cada comentario TODO, FIXME y HACK a un formato estructurado. Incluye la ruta del archivo, el número de línea y dos líneas de contexto.
2. Contextualización: Mapea las fechas de creación de los archivos con los comentarios. Un TODO de 2019 en un archivo que ha sido refactorizado diez veces desde entonces es probablemente un fantasma.
3. Agrupación: Agrupa los comentarios por directorio o módulo. Esto permite que el desarrollador permanezca en un solo modelo mental mientras revisa tareas relacionadas.
4. Análisis con agentes: Utiliza agentes de codificación con IA para leer la lógica circundante. Un agente a menudo puede determinar si un comentario sigue siendo relevante verificando el estado actual de la implementación.

Cuando utilizas coding agents para asistir en este proceso, la velocidad del triaje aumenta significativamente. Un agente puede navegar entre code and git files para ver quién escribió el comentario y si la lógica referenciada aún existe.

Gestión del espacio de trabajo durante el triaje

Gestionar años de deuda es una tarea de alto contexto. Normalmente estás mirando el código fuente, la salida de la terminal de una búsqueda y la documentación del proyecto simultáneamente. Las interfaces de pestañas estándar a menudo se quedan cortas porque requieren cambiar constantemente entre vistas, lo que provoca fatiga de memoria.

Una alternativa es usar un canvas infinito. Al colocar los resultados de búsqueda en un panel, el editor de código relevante en otro y una terminal para pruebas en un tercero, puedes ver el ciclo de vida completo de un error sin perder la concentración. En Deska, puedes ejecutar múltiples herramientas como Claude Code o OpenCode lado a lado en paneles dentro del espacio de trabajo. Esto permite que un agente busque patrones mientras tú verificas manualmente las decisiones arquitectónicas críticas.

Debido a que el triaje involucra lógica interna sensible, a menudo se prefiere un enfoque local-first. Mantener el código y los datos de la sesión en tu máquina garantiza que tu mapa de deuda técnica no se filtre a una nube de terceros. Puedes gestionar estas sesiones a través de la configuración de data and storage que prioriza la privacidad.

Comparación de estrategias de triaje

Diferentes equipos abordan la deuda de diversas maneras. Algunos prefieren un "Viernes de limpieza" donde cada persona elige cinco comentarios para arreglar. Otros prefieren un equipo de trabajo centralizado.

Herramientas como SonarQube o ESLint difieren en su enfoque respecto a los agentes de codificación especializados. Mientras que las herramientas de análisis estático encuentran errores basados en reglas de sintaxis, los agentes pueden entender la intención detrás de un comentario en lenguaje natural. Para un repositorio de cinco años, combinar ambos es la estrategia más robusta.

Aprovechando los espacios de trabajo modernos

Si estás usando Deska para este proceso, el asistente Ask Deska puede acelerar la configuración. Puedes usar tu voz o un comando de chat para abrir cuatro terminales, navegar a directorios específicos e iniciar una sesión de agente de codificación. Esto reduce la fricción de comenzar una sesión de trabajo profundo.

Si necesitas alejarte de tu escritorio, la aplicación mobile te permite monitorear tareas de agentes que tardan mucho tiempo. Dado que los dispositivos se vinculan directamente sin exponer puertos, puedes verificar si un agente ha terminado de escanear el directorio /src mientras estás fuera de la oficina. También puedes revisar las notifications para ver si se marcó alguna vulnerabilidad crítica durante el triaje.

FAQ

¿Cómo automatizar la gestión de comentarios todo?

La automatización implica el uso de ganchos de git (hooks) para evitar nuevos TODOs sin etiqueta y el empleo de agentes de IA para escanear los existentes. Los agentes pueden categorizar comentarios verificando si el código al que se refieren ya ha sido actualizado.

¿Son seguros los agentes de IA para repositorios internos?

La seguridad depende de la arquitectura de la herramienta. Las herramientas locales que utilizan tus propias llaves de API o modelos de inferencia local garantizan que tu lógica patentada permanezca en tu hardware en lugar de ser utilizada para entrenamiento.

¿Cómo priorizar la deuda técnica antigua?

La priorización debe basarse en la frecuencia de ejecución y el impacto en el negocio. Utiliza un perfilador (profiler) para ver si un TODO existe en una ruta crítica de la aplicación. Si la deuda afecta el rendimiento o la seguridad, se mueve al principio de la lista.

Comienza a limpiar tu base de código

Gestionar años de deuda técnica no tiene por qué ser una tarea manual tediosa. Al combinar recetas de triaje estructuradas con un espacio de trabajo flexible y local, puedes convertir una montaña de comentarios en una hoja de ruta manejable. Puedes descargar (download) la aplicación de escritorio de Deska para Mac, Windows y Linux para comenzar a organizar tus paneles y agentes hoy mismo.