Número de comentarios TODO
| 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): losTODOson 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; losTODOson 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 (unTODOen 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.TodoCommentCountRecursivePackageincluye 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.