Opiniones sobre los comentarios en el código de un programa hay tantas como formas de colocarlos y expresar ideas con éstos. Y, ciertamente, creo que, en general, a la mayoría de los programadores no nos gusta escribir comentarios casi tanto como nos nos gusta elaborar la documentación de nuestras creaciones.

Tras más de 30 años en el negocio, que me ha tocado ver de todo: desde organizaciones que requieren la documentación como se dicta en libros, publicaciones, o los métodos más pedantes, hasta aquellas que no sólo no les importa sino que lo desalientan. Sip, hay de todo en esta vida.

Yo estoy convencido que los comentarios y la documentación (pese a la flojera que me da ésta última) son necesarias. Incluso para uno mismo, son muy útiles las anotaciones en el código para más rápido entender lo que pasaba por nuestra mente cuando lo elaboramos, recordar el enfoque y solución adoptada. Ahorra tiempo para poder «leer» el código y volver a adquirir ese estado mental. Desafortunadamente esto no es del todo cierto si hablamos de compartir el código con alguien más o esperamos facilitarle la vida a alguien más en el futuro, cuando otro pobre diablo le toque mantener las monstruosidades que elaboramos. A veces no importa qué tan claro hagamos el código o qué tantos comentarios incluyamos, hay gente que no se siente a gusto leyendo código ajeno y prefiere reescribirlo.

A pesar de esta utilidad y necesaria información que los comentarios incluidos en el código proveen, también comparto ese sentimiento de ofuscación o estorbo que puede ser abrir un archivo y encontrarse con dos o tres pantallas de comentarios de identificación obligados por alguna política o metodología, así como bloques de varias líneas describiendo cosas en el código, algunas de las cuales son evidentes. Sí, lo comentario son útiles pero pueden ser una monserga también.

Cómo sea, a la fecha, no he visto o encontrado una plantilla o algo que me brinde la idea de lo que debería ser el esquema ideal sobre la estructura y estilo que deben tener los comentarios de un programa. A lo largo de mi experiencia profesional he visto y escuchado reglas o consejos por ahí y por allá y he desarrollado un cierto estilo personal en los últimos años y, buscando dar una definición final a éste, he creado una página al respecto.