Comentarios que huelen
Publicado el 2025-05-14
¿Conoces esa sensación de revelación cuando alguien te descubre el nombre de un concepto que sólo intuyes?
A mí me pasó recientemente al oír a Matt Godbolt hablar sobre 'comentarios que huelen' ('comment smells' en el inglés original). Es un concepto que menciona en su charla "Correct by Construction: APIs That Are Easy to Use and Hard to Misuse" 1, la cual recomiendo escuchar en su totalidad.
Matt ofrece como ejemplo una API cuyos comentarios en código fuente indican al usuario que debe llevar a cabo pasos adicionales de montaje o desmantelamiento. En vez de endosarle al usuario la responsabilidad de leer comentarios y actuar según dichas instrucciones, Matt nos urge a los programadores a que afloremos estos requisitos en la API mediante código, contratos y firmas de funciones. De este modo ¡convierte mensajes para humanos en mensajes para el compilador! (Preferiblemente del tipo que llevan a errores en tiempo de compilación.)
En concreto Matt menciona los ‘comentarios disculpa’ como una mala práctica, y son estos los que deben eliminarse y codificarse en la API misma.
Toda la charla merece la pena, incluso para alguien que jamás haya escrito una línea de C++ en la vida. La charla está disponible en YouTube, y es en el minuto 31:10 cuando habla sobre 'comentarios que huelen'.
Imagen: Fig. 113 de Plain Home Talk (1896) por Edward B. Foote, fuera de copyright.