Gañanada Nº 001
El comentario que lleva tres años mintiendo
- Categoría
- Código arqueológico
- 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
- 1Python — doctest: ejemplos de documentación que se ejecutan como pruebas
- 2Robert C. Martin, «Clean Code», capítulo 4 («Comments») — Sobre los comentarios que sustituyen a un buen nombre y los que envejecen mal.