Número de comentarios TODO

Actualizado el 15 de noviembre de 2026

Sigla TODO (TODO(rec) en la variante recursiva de paquete)
Aspecto «Documentación»
Se mide en método, clase, interfaz, paquete, módulo, proyecto, tipo de fichero
Tipo de valor recuento (entero, mínimo 0)
Dirección informativa: ni alto ni bajo es mejor
Stau Metro TodoCommentCountMethod, TodoCommentCountClass, TodoCommentCountInterface, TodoCommentCountPackage, TodoCommentCountRecursivePackage, TodoCommentCountModule, TodoCommentCountProject, TodoCommentCountFileType

En pocas palabras

Cuenta las anotaciones del tipo «TODO: hacer esto luego» que los programadores dejan en los comentarios. Es una forma barata de ver cuánto trabajo pendiente está apuntado en el código y dónde se acumula.

Qué mide

La deuda técnica señalada de forma explícita: lo que alguien reconoció que falta, que está provisional o que hay que arreglar, y lo escribió. No ve la deuda que nadie apuntó. Un valor 0 no significa que el código esté completo; solo que no hay marcadores.

Un marcador de este tipo suele ser una promesa. Si crece sin que se resuelvan los antiguos, los TODO dejan de ser un recordatorio y se vuelven ruido.

Cómo se calcula

Es un recuento de elementos TODO: el número de coincidencias que encuentra la búsqueda de patrones TODO del entorno de desarrollo dentro del texto del elemento. La métrica no define qué es un TODO; lo define el IDE, que por defecto reconoce TODO y también FIXME (la configuración del IDE puede cambiar los patrones, y entonces cambia la métrica sin tocar el código).

Ejemplo

import java.nio.file.Path;

class Importer {
    void load(Path file) {
        // FIXME: closes the stream too early
        read(file);
    }

    void read(Path file) {
        // reads the file
    }

    // TODO: handle encodings other than UTF-8
}

Con los patrones por defecto: load tiene 1 (FIXME), read tiene 0 y la clase Importer tiene 2 (el FIXME de load más el TODO del final, que está dentro de la clase aunque fuera de los métodos).

Cómo interpretarla

Es una métrica informativa, sin umbrales de referencia. Es útil:

  • en el tiempo: si el total crece versión tras versión, se acumula deuda apuntada;
  • entre elementos: los que más marcadores concentran suelen ser los que se escribieron con prisa;
  • como lista de trabajo: el valor es un número, pero lo que importa es leer cada comentario.

Un TODO que lleva años sin resolverse es una decisión de no hacerlo: bórralo o conviértelo en una tarea con dueño en el gestor de incidencias.

Relación con otras métricas

  • «Líneas de comentario» (CLOC): los TODO son un tipo de comentario; se leen juntas para saber qué parte de los comentarios son tareas pendientes.
  • «Ratio de deuda técnica» (TDR): estima la deuda técnica a partir de reglas y esfuerzo; los TODO son su equivalente manual y explícito.

En las herramientas

Stau Metro. Usa la búsqueda de patrones TODO del IDE, no una expresión propia, y cuenta los elementos dentro del rango de texto del elemento:

  • Método (TodoCommentCountMethod): todo el texto del método, incluidos su Javadoc (un TODO en el Javadoc cuenta para su método), las lambdas y las clases anónimas o locales que contenga.
  • Clase (TodoCommentCountClass) e interfaz (TodoCommentCountInterface): todo el texto de la clase, incluidas sus clases anidadas. Los enumerados y los records tienen valor de clase; los tipos de anotación no tienen valor ni de clase ni de interfaz. A diferencia de las «líneas de comentario», el valor de la clase exterior sí incluye lo de las interiores, y sumar los valores de todas las clases cuenta dos veces los marcadores de las anidadas.
  • Paquete (TodoCommentCountPackage), módulo (TodoCommentCountModule) y proyecto (TodoCommentCountProject): suma por fichero, de cualquier lenguaje, con los ficheros de test incluidos y también lo que esté fuera de las clases. TodoCommentCountRecursivePackage incluye los subpaquetes.
  • Tipo de fichero (TodoCommentCountFileType): igual, agrupado por tipo.

Qué palabras cuentan depende de la configuración del IDE. En los ficheros que no son Java, el resultado depende también de cómo reconozca el IDE los comentarios de cada lenguaje.