Barrapunto

Hay gente que cree que tiene que describir en los comentarios lo que hace el código. Leer un fichero de cierto tamaño comentado por una de esas personas es insufrible, pues vas leyendo lo mismo dos veces en paralelo.

a = b * 2; /* asigno a "a" el valor de "b" multiplicado por dos */

Si notas la profunda estupidez de ese comentario, estás en el camino para entender por qué "Abro una conexión con base de datos", "Cierro el fichero" y similares son comentarios pésimos.

¿Qué es lo que hay que poner en un comentario? La pregunta que tienes que hacerte es:

¿Por qué?

O sea ¿por qué he hecho esto... que no es evidente por sí mismo? Hay que ponerse en el lugar del que va a leer el código (que puede ser uno mismo) y señalar las partes en que se hace algo que no se entiende a primera vista.

Aparte de eso, es conveniente escribir descripciones detalladas para cada módulo, clase y función que se escriba, pero eso es posible hacerlo "asíncronamente", es decir antes o después de escribir el código, mientras que lo del por qué es conveniente hacerlo a la vez.

Una variante de esos comentarios es convertirlos en sentencias de salida (ya sea a base de prints o algo mas elaborado como un servicio de logging).
Retocandolos un poco para que sepas el contenido, "abriendo base de datos '$bd' con usuario '$user'".

A parte de eso, los comentarios mas utiles son los que indican que parametros de entrada, que parametros de salida, que se quiere hacer y que otros modulos se tocan (para evitar posibles efectos laterales). Esto es lo mas basico, basico de cualquier documentacion.

Si notas la profunda estupidez de ese comentario, estás en el camino para entender por qué "Abro una conexión con base de datos", "Cierro el fichero" y similares son comentarios pésimos.

Creo que son ejemplos distintos... a=b*2; es fácil de entender por cualquier persona, pero cuando te pones con fopen y similares quizás no lo sea para todo el mundo... ya estamos hablando de otras cosas.

Yo uso bastantes comentarios, como forma didactica.