Skip to the content ForoHackers
Log inJoin

Documenta el porqué, no el qué: lecciones de un programa de 1987

DocumentationMaintenance and legacy codeTechnical writing
#1061 · LaAbuelaDelCOBOL · · Report

He heredado muchos programas con comentarios. Casi todos así:

* SUMA 1 AL CONTADOR
ADD 1 TO WS-CONTADOR.

Eso lo dice el código. No hace falta que lo diga una mujer de 60 años con un lápiz rojo.

El comentario que me salvó un viernes fue este, en un programa de 1987:

* LOS REGISTROS DE TIPO 'X' SE SALTAN A PROPOSITO: LOS GENERA
* EL SISTEMA DE SUCURSALES Y LLEGAN DUPLICADOS. VER INCIDENCIA DE 1991.
IF TIPO-REG = 'X' GO TO SIGUIENTE.

Sin ese comentario, alguien habría "arreglado" el salto y duplicado medio millón de apuntes.

Mi regla: el código dice cómo, el comentario dice por qué (y a veces por qué no). Y un documento corto de "decisiones" al lado del programa, con la fecha, vale más que cien páginas de manual que nadie actualiza.

#1609 · PacoElDelCronjob · · Report

+1. El comentario que más he agradecido en mi vida decía: "no tocar, ya sé que parece feo". Tenía razón. Lo toqué. Tenía razón.

#1610 · ElDelPuntoYComa · · Report

Con permiso, un matiz de pedante cariñoso: el "por qué" también envejece. Conviene que el comentario cite algo que se pueda comprobar (un identificador de incidencia, una fecha), no solo una opinión. Así, cuando la causa desaparece, alguien puede decidir con datos si el código sigue siendo necesario.

#1611 · VermutConVim · · Report

Yo añado el mensaje de commit: ese es el sitio natural para el "por qué" de un cambio. Con git blame llegas a la línea y con el mensaje llegas a la razón. Un commit que dice "fix" es un comentario que se ha ido de vacaciones.

#1612 · LaAbuelaDelCOBOL · · Report

Tiene razón Punto y Coma: la incidencia de 1991 existía en papel y por eso la cité. El día que el papel se perdió, el comentario era lo único que quedaba del motivo. Escribe el porqué donde el código vive.

Log in or join to reply.