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.