Saltar al contenido
AXXA

Gañanada Nº 002

El TODO que heredarán tus nietos

Gravedad
II — Moderado
Fecha del hallazgo
Etiquetas
  • #todo
  • #deuda-tecnica
  • #backlog
  • #comentarios

Descripción del hallazgo

En la cabecera de un controlador de comunicaciones serie se encontró este fósil, en un estrato datado en 2014:

/* TODO: quitar esto antes de la demo. (JMR) */
#define UART_TIMEOUT_MS 30000 /* temporal */

La demo se celebró. El producto se vendió. Se migró de CVS a Subversion y de Subversion a Git conservando el historial, un esfuerzo encomiable que garantizó que el TODO llegara intacto a nuestros días. JMR dejó la empresa en 2016. El temporizador temporal sigue siendo de treinta segundos.

Un inventario rápido reveló que no se trataba de un ejemplar aislado, sino de una colonia:

$ grep -rnE "TODO|FIXME|HACK|XXX" src/ | wc -l
1342

Contexto del descubrimiento

La investigación empezó por una queja de un cliente: cuando un periférico se desconectaba, la interfaz se quedaba congelada medio minuto antes de mostrar el error. Dos ingenieros dedicaron una semana a perfilar el bucle de eventos, revisar el planificador y sospechar del firmware del periférico. La causa estaba en la línea 41 de un archivo de cabecera, anunciada en mayúsculas.

El análisis posterior de la colonia arrojó algunos datos de interés etnográfico:

Tipo de nota Ejemplares Proporción
Firmadas por personas que ya no están en la empresa 416 31 %
Que mencionan «la demo» sin especificar cuál 163 12 %
Con referencia a una incidencia existente 21 1,6 %
Que dicen exactamente «TODO: mejorar» 88 6,6 %

Ninguna tenía fecha. Doce eran anteriores al propio sistema de control de versiones, porque se importaron desde un archivo comprimido llamado version_buena.zip.

Consecuencias observadas

  • El ruido oculta la señal. Entre 1 342 notas, la única que importaba era indistinguible de las 88 que dicen «mejorar».
  • Deuda invisible para quien decide. Ninguno de estos trabajos pendientes figuraba en el backlog, así que nunca compitió por prioridad con nada.
  • Parálisis por miedo. Nadie se atreve a borrar un TODO ajeno: quizá todavía significa algo. Nadie se atreve a resolverlo: quizá ya no.
  • Costes reales. Una semana de dos ingenieros, más el tiempo que el cliente pasó mirando una interfaz congelada.

Recomendación de la academia

Un TODO es una incidencia sin gestor de incidencias: no tiene responsable, ni prioridad, ni fecha. Si el trabajo importa, merece una entrada en el backlog; si no importa, no merece una línea en el código.

Reglas sencillas que funcionan:

  1. Todo TODO referencia una incidencia: TODO(COM-1234): …. El comentario explica el contexto local; la incidencia, el porqué y la prioridad.

  2. Hazlo obligatorio en la integración continua. No hace falta una gran herramienta:

    # Falla si hay un TODO sin incidencia asociada
    if grep -rnP 'TODO(?!\([A-Z]+-\d+\))' src/; then
      echo "Hay TODO sin incidencia asociada" >&2
      exit 1
    fi
  3. Usa caducidades donde el ecosistema lo permita, como la regla expiring-todo-comments de ESLint, que rompe el lint cuando vence la fecha o la versión indicada.

  4. Haz triaje periódico de la colonia existente: cada nota se convierte en incidencia, se resuelve o se borra. Las tres opciones son mejores que conservarla.

El código no es un buzón de sugerencias para el futuro. El futuro no lee los comentarios: los hereda.

No trabajes así, no seas un gañán.

Referencias

  1. 1eslint-plugin-unicorn — regla «expiring-todo-comments» — TODO con fecha o versión de caducidad que rompen el lint cuando vencen.

Véase también