Saltar al contenido
AXXA

Gañanada Nº 001

El comentario que lleva tres años mintiendo

Gravedad
III — Grave
Fecha del hallazgo
Etiquetas
  • #comentarios
  • #documentacion
  • #mantenibilidad
  • #nombres

Descripción del hallazgo

En el módulo de licencias de una aplicación de escritorio aparece la siguiente pieza, conservada en perfecto estado:

/**
 * Devuelve true si la licencia ha caducado.
 */
export function checkLicense(license: License): boolean {
  return license.expiresAt.getTime() > Date.now();
}

El comentario es claro, conciso y está bien formateado. Solo tiene un defecto: es falso. La función devuelve true cuando la licencia sigue vigente. Lleva tres versiones haciéndolo.

Lo más notable del espécimen no es el error, sino el ecosistema que ha crecido a su alrededor. Los puntos de llamada se adaptaron hace tiempo a la mentira:

// No tocar: el comentario de checkLicense está mal, pero funciona.
if (!checkLicense(license)) {
  showExpiredDialog();
}

El sistema funciona correctamente porque todo el mundo sabe que la documentación miente. Todo el mundo, salvo la persona que acaba de llegar y, por desgracia, lee la documentación.

Contexto del descubrimiento

El comentario original fue escrito por alguien que, a juzgar por la evidencia, entendía el sistema. La función se llamaba entonces isLicenseExpired y comparaba las fechas en el sentido contrario. En la versión 4.2, durante una refactorización titulada «sin cambios funcionales», alguien la renombró, invirtió la comparación y ajustó los catorce puntos de llamada. Todo menos el comentario.

Desde entonces, la implementación ha evolucionado, pero el comentario se ha mantenido fiel a sus principios: no cambiar nunca.

El hallazgo se produjo cuando una incorporación reciente, siguiendo escrupulosamente la documentación, añadió una comprobación al arranque: if (checkLicense(license)) blockApplication();. Funcionó a la primera. Bloqueó la aplicación a todos los clientes con licencia válida durante cuarenta minutos de un martes por la mañana, y la dejó abierta, con total generosidad, a los que la tenían caducada.

Consecuencias observadas

  • Induce a error a cualquiera que lea la firma antes que la implementación, es decir, a quienes trabajan como se debe.
  • Provoca investigaciones innecesarias: el código es correcto, los llamantes son correctos y, aun así, nadie se fía de nada.
  • Genera conocimiento tribal («ese comentario está mal, todo el mundo lo sabe») que no figura en ningún sitio y se pierde con cada baja.
  • Aumenta la entropía del repositorio. Un comentario falso es peor que ninguno: además de no ayudar, compite con el código por la autoridad.

Recomendación de la academia

Si cambias el comportamiento de una función, actualiza también su documentación. Los comentarios no son artefactos arqueológicos que deban preservarse por su valor histórico.

Mejor aún: haz innecesario el comentario sobre el qué. Un nombre como isLicenseValid no puede desincronizarse de su documentación porque es su documentación. Reserva los comentarios para lo que el código no puede expresar: el porqué de una decisión, una restricción externa, el enlace a la incidencia que explica una rareza.

Práctica Qué protege
Nombres que expresan la intención (isLicenseValid) Elimina la necesidad del comentario
Revisar los comentarios del diff en la revisión de código Detecta la desincronización cuando se produce
Ejemplos ejecutables (doctests, tests con nombre descriptivo) Documentación que falla si deja de ser verdad
Comentarios que explican el porqué, no el qué Reduce la superficie que puede quedar obsoleta

Un comentario es una afirmación sin compilador. Trátalo con la misma desconfianza que un test que nunca se ejecuta.

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

Referencias

  1. 1Python — doctest: ejemplos de documentación que se ejecutan como pruebas
  2. 2Robert C. Martin, «Clean Code», capítulo 4 («Comments») — Sobre los comentarios que sustituyen a un buen nombre y los que envejecen mal.

Véase también