TODO en realidad no es algo "para resolver"

• Algunos equipos usan políticas como registrar todos los comentarios TODO en el bug tracker o borrar automáticamente los TODO con más de un año, pero no se recomienda esta práctica
• Los comentarios TODO no son necesariamente cosas que solo tienen valor si se completan, sino que funcionan como una instantánea mental que deja el contexto y las ideas del momento en que se escribió el código
• Los TODO importantes deberían gestionarse como issues, pero la mayoría son notas de baja prioridad o apuntes sobre edge cases
• Un TODO bien ubicado le da al futuro lector del código pistas para entender la intención del autor de ese momento cuando se pregunta "¿está bien refactorizar esta parte?"
• El valor de un TODO no está en si se completa o no, sino en registrar contexto, intención y posibilidades para ayudar al mantenimiento y la colaboración en el futuro

---

Comentarios TODO: ¿de verdad hay que resolverlos?

• En algunas organizaciones se aplican reglas como registrar todos los TODO del código en el bug tracker o borrarlos automáticamente después de cierto tiempo (más de un año)
• Sin embargo, este enfoque es en realidad ineficiente y pierde de vista la esencia de un TODO: no adquiere valor solo cuando se resuelve

El verdadero valor de TODO

• Por ejemplo, un comentario como

  // TODO: 다음 주 출시 전에 이 파일의 뒷부분을 완성해야 함  
  

  sí podría necesitar seguimiento real

• Pero un buen TODO suele servir, más bien, para registrar edge cases o dejar ideas de mejora estructural que no se pudieron abordar en ese momento, situaciones omitidas, etc., junto con su contexto, como en

  // TODO: 사용자가 이 버튼을 트리플 클릭할 경우, 핸들러에서 \[xyz] 오류 발생  
  

TODO no es un "plan", sino un "canal"

• La mayoría de los TODO en realidad son de baja prioridad y no necesitan resolverse de inmediato
• Cumplen la función de transmitir al futuro lector del código las dudas, criterios y contexto del autor en el momento de escribirlo
• Cuando alguien lea ese código más adelante y se pregunte "¿se puede cambiar la estructura aquí?", el TODO ayuda a entender la intención original del autor

Efectos de un TODO bien escrito

• Los TODO dentro del código a veces ofrecen pistas importantes sobre posibles problemas, oportunidades de mejora estructural o edge cases no resueltos
• Aunque no sean necesariamente un plan para solucionar algo, cumplen un papel clave al transmitir contexto sutil en la colaboración y el mantenimiento
• Al final, los comentarios TODO funcionan como un valioso registro que mejora la comprensión del código y su futura mantenibilidad

Conclusión

• Un TODO no tiene valor solo si se completa; también funciona como un canal de comunicación que deja los pensamientos, la intención y el contexto del autor para los futuros lectores del código

[GN⁺]

Opiniones en Hacker News

• Yo soy de la postura de que "todo TODO siempre debería estar vinculado a un issue concreto"
  Creo que hay tres formas de resolver un TODO antes del merge
  1. Dejar un issue: si realmente es algo que hay que hacer, conviene invertir unos 20 segundos en registrarlo y darle seguimiento
  2. Resolverlo de una vez: si es algo demasiado pequeño como para convertirlo en issue, se arregla antes del commit
  3. Convertirlo en comentario: si no vale la pena corregirlo ni hace falta rastrearlo, pero quieres recordarlo, recomiendo dejarlo como comentario normal en el código
  Si te importa la salud del proyecto, conviene tener el hábito de rastrear los TODO, como quien come brócoli por salud
  • Hacer seguimiento en un sistema externo no es solo crear el issue; también implica clasificarlo, manejar el backlog, reclasificarlo, cerrarlo cuando se complete, etc.
    Un issue registrado en un sistema externo puede no ser visible para quienes tocan esa parte del código
    Si te parece un desperdicio el costo de rastrear cosas sencillas que se podrían arreglar fácil, entonces es más eficiente dejarlas como TODO
    Los TODO dentro del código se ven de inmediato al trabajar en esa parte, y también se pueden borrar fácilmente durante un refactor
  • Parece que el autor del texto apoya básicamente la opción 3 (dejarlo simplemente como comentario)
    Pero da pena que no haya explicado con claridad la diferencia entre un comentario TODO y un comentario normal
    El término TODO en sí tiene mucha fuerza visual, así que deja claro de inmediato qué tipo de comentario es
    Me genera cierta duda eso de sostener que no hace falta interpretar TODO literalmente como “por hacer”
    En general estoy de acuerdo con el artículo, pero creo que sería mejor dejarlo simplemente como comentario normal
  • Dice que “solo hay que invertir 20 segundos en registrarlo y administrarlo”, pero eso precisamente ya es un TODO
    Si además lo subes a un sistema de tickets, toma mucho más de 20 segundos y, en vez de ayudar, termina generando distracción
  • Ojalá el rastreo tomara 20 segundos, pero (por ser una gran empresa) para crear un ticket en JIRA hay más de 10 campos obligatorios
  • Yo solo uso una regla: todo TODO debe incluir obligatoriamente un número de ticket
    // TODO: improve the routing https://jira.com/whatever/TIX-1234
    La razón es que, si el comentario queda huérfano, nadie sabe por qué se dejó ahí
    Si dejas solo el comentario, después alguien olvidará su propósito y contexto
    Por eso creo que siempre hay que crear un ticket o resolverlo de inmediato
• Yo los diferencio así cuando hago grep
FIXME: algo claramente incorrecto o roto, máxima prioridad
  XXX: algo feo de ver o con suposiciones incorrectas, prioridad alta
  TODO: algo donde algún día habrá que implementar un enfoque/categoría/rama completamente nuevos
  NOTE: para transmitir información más importante que un comentario simple
  Yo trabajo sobre todo en motores de código legacy o sin mantenimiento, y aquí “el código es la verdad”, así que no creo JIRA, sino que voy leyendo y corrigiendo sobre la marcha
  • Yo lo uso así
    TODO: trabajo imprescindible antes del release, algo obligatorio. Si no entra en eso, debería pasar a otra categoría. Bloquea el release
    FUTURE: algo que algún día podría convertirse en TODO, normalmente opcional, como diseño estructural
    MAYDO: estaría bien tenerlo, pero no pasa nada si no está
    PERF: convendría hacerlo cuando haga falta más rendimiento
    Y además uso etiquetas semánticas relacionadas con el dominio
    Mi opinión es que TODO no es un code smell, sino algo que se acumula naturalmente en partes centrales del codebase
  • Yo uso XXX como nota personal de “esto hay que arreglarlo antes del siguiente PR”
    Si quiero ponerme serio, configuro el CI para que rechace cualquier código que contenga esa cadena
    En ese sentido, para mí XXX tiene la prioridad más alta
  • Me gusta este estilo. En un proyecto, teníamos el CI configurado para rechazar cualquier código con FIXME, y también cualquier TODO sin ticket de issue
    Ordenándolo por prioridad hacia abajo
    FIXME: para mantener el enfoque. Tiene que resolverse antes del merge o antes de que el código se considere terminado
    XXX: hay que corregirlo pronto. Funciona por ahora, pero debe arreglarse en poco tiempo
    TODO: hay que volver a revisarlo después. El código se puede usar perfectamente. Tiene menos prioridad que XXX
NOTE: explica rarezas o cosas que conviene saber para ayudar a quien trabaje después
  • Yo hago algo parecido. En rutas de código todavía incompletas pero evitables, pongo assert en vez de FIXME
    Uso TODO para dejar posibles tareas como refactors, mejoras de rendimiento o de claridad
    Uso NOTE para dejar contexto histórico o líneas de pensamiento que no se entienden fácilmente a simple vista
  • En teoría suena bien, pero creo que este tipo de acuerdos no sirven de mucho sin soporte de herramientas
    Si además asumes que se trabaja en equipo, todavía más
    Eso no significa que diga que no tengan valor; más bien creo que hacen falta o deberían crearse herramientas para esto
• Me recuerda al dicho de que lo perfecto es enemigo de lo bueno
  Este tipo de deuda técnica o code smells en realidad debería rastrearse, registrarse y explicarse mejor, pero si propones hacer algo que baja la productividad, como usar JIRA, al final la gente deja de registrar cualquier cosa
  Al menos si hay un TODO dentro del código, queda en algún lugar
  Y un TODO sí tiene significado porque también es literalmente algo “por hacer”
  • En codebases grandes, los TODO de muchas personas pueden mezclarse y volverse caóticos, pero para proyectos personales es una buena solución de compromiso
    “Sé que podría hacerse mejor, pero no voy a interrumpir mi flujo a propósito por eso. No rompe la funcionalidad; simplemente estaría un poco mejor si se hiciera.”
    Cuando el resaltado de TODO reaparece en el editor, a veces ayuda para resolver uno rápidamente
    Pero la mayoría de los TODO se quedan para siempre, o en la práctica casi nunca se resuelven
  • A veces termino dejando un TODO porque quiero dejar una señal en el código de que hay algo pendiente por tratar
    Aunque lo registres en JIRA, GH Issues, etc., al final ese registro tiene que estar conectado
    Y si solo dejas una referencia, puede perder el significado con el tiempo, así que el comentario también debería incluir una explicación
  • Ya existe incluso una función en Cursor que ejecuta directamente un servidor MCP para que la IA cree tickets de JIRA
  • Creo que dejarlo en el mensaje del commit es mucho mejor
    Muchos commits en realidad no transmiten bien su contenido
    En vez de seguir dejando TODO como antes, preferiría que se promoviera usar mejores herramientas
    Mucha gente hace commits con muy poca frecuencia y mete varios trabajos distintos en uno solo
    Además, los mensajes de commit muchas veces son cosas sin sentido como updating somefile.py
• Esto es una cuestión de estilo. Cada quien puede tener una definición o cultura distinta respecto a TODO
  En mi codebase, TODO se usa tal como se describe aquí
  TODO sirve para documentar la implementación, especialmente las partes faltantes; no implica necesariamente que haya que resolverlo
  A mí me parece que dejar una lista real de tareas dentro del código no tiene mucho sentido. Las prioridades cambian constantemente: algo pudo ser importante cuando se escribió, pero luego ya no, y también pueden aparecer problemas no previstos que terminen siendo más urgentes
  No puedes estar levantando PRs continuamente solo para actualizar comentarios TODO
  Si quieres anotar tareas, es mejor gestionarlas fuera del código, en un issue tracker o en un documento de texto fácil de actualizar
• El título es un poco baitero, pero estoy totalmente de acuerdo con el contenido completo
  Justo ahora dejé un #TODO para registrar una situación excepcional que ocurre extremadamente raro. En dos años no ha pasado ni una sola vez, pero me ayuda por si luego me pregunto por qué no manejé esa parte
  Entiendo a quienes dicen que cosas así a veces deberían quedarse como comentarios normales. Depende del tipo de codebase, y en un entorno como el mío, de equipo de dos personas, el enfoque de TODO funciona bien
  • En nuestro equipo usamos // TBD: [...] para ese propósito. Era un truco para que la gente obsesionada con los TODO no se diera cuenta
• Hace falta un lugar para registrar problemas conocidos que claramente tienen valor, pero no necesitan seguimiento
  No planeas arreglarlos realmente, pero quizá cuando tengas tiempo más adelante quieras buscarlos con un ctrl-F para ver si vale la pena limpiar algo
  Me parece irracional que demasiadas herramientas o procesos consideren TODO como un code smell
  • Yo en realidad todavía no me he topado con ese tipo de problema
    Para mí es solo una cuestión de prioridades y, al final, lo veo como una “ventana rota” (la famosa metáfora de The Pragmatic Programmer)
    Si de verdad decidiste no arreglarlo, es mejor registrarlo en la documentación del software
• En el artículo ponen como ejemplo

  // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
  A mí eso no me parece un TODO real, sino más bien un comentario normal
  Este tipo de comentarios explicativos sin duda ayuda, pero cuesta llamarlos TODO
  Un TODO debería señalar algo que realmente hay que hacer, es decir, algo que debe cambiar, como “esta función debería devolver un valor distinto según XYZ”
  En ese sentido, un TODO no debería quedar enterrado en el código, sino estar en el issue tracker
  Por experiencia, los TODO son solo una manera de justificar sacrificar calidad de código por sacar rápido la aprobación del PR. En la práctica casi nunca se ejecutan, y solo dejan esa idea de “algún desarrollador junior con más tiempo lo arreglará algún día”

  • Los comentarios sirven para explicar por qué este código funciona de esta forma
    Por ejemplo, si solo pones
    // If the user triple-clicks this button, the click handler errors because [xyz]
    así nada más, no queda claro si eso es un bug o si era la intención original
    TODO es una señal simple de “aquí hay algo imperfecto, tenlo en cuenta cuando trabajes en esto”
    Si de verdad es algo que debe resolverse, entonces sí corresponde rastrearlo en otro lugar
    Pero creo que si reduces demasiado los TODO, lo único que logras es aumentar el código sin documentar
  • No me parece que ese ejemplo sea un comentario TODO especialmente bueno
    En el tiempo que tardas en escribir eso, mejor arreglas el bug de una vez o dejas un comentario como “el triple clic se ignora por [xyz]”
    Si ya identificaste el disparador y la causa, yo diría que el 80% del trabajo ya está hecho
  • Eso se puede ver más bien como “omitirlo”. Muchas veces no pasa nada si nunca se trabaja en ello
    El problema es cuando se asume que el código funciona perfectamente aunque no sea así
    El mejor TODO que he visto decía algo como TODO: encrypt this en código de seguridad, dejando clarísimo que eso todavía no estaba cifrado
    Gracias a eso, cualquiera podía notar rápido que el código no estaba cifrando, y también se reducía la duda de si tal vez el cifrado se estaba manejando aparte por modularidad o si había que preocuparse por cifrar dos veces
  • El ejemplo que dieron se parece más a FIXME que a TODO
    Claramente es un error, pero no parece que haya demasiada urgencia por atenderlo
• Estoy fuertemente en desacuerdo
  Si no lo vas a registrar como bug o no vas a trabajarlo de verdad, preferiría que no dejaras un TODO
  // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
  Eso solo registra el fenómeno observado. Lo correcto sería quitar la palabra TODO
• Yo también lo uso de forma jerárquica
  FIXME lo uso cuando de verdad hay que arreglar algo o cuando ya tengo clarísimo cuál es el siguiente paso
  TODO lo uso para ideas más vagas, o simplemente para sacarlas de mi cabeza y poder concentrarme en lo siguiente
  Puede ser porque la idea todavía no madura, porque no estoy seguro de que realmente haga falta, o porque estoy esperando algo relacionado, entre muchas otras situaciones
  Si no lo anoto, me sigue rondando en la cabeza y me distrae; con escribirlo como TODO o como sea, psicológicamente me siento mucho más liberado
• Yo veo los comentarios como prueba de una capacidad deficiente para escribir código
  Ojalá uno pudiera escribir código tan claro que se entendiera de inmediato sin comentarios
  Aun así, si queda tan confuso que ni yo mismo lo entendería después, no queda otra que comentar
  Lo triste es que, si luego alguien modifica el código y no actualiza el comentario, termina generando todavía más confusión
  Creo que los TODO no deberían existir en código ya committed; deberían gestionarse en el proyecto o en el sistema de seguimiento de issues correspondiente