Maldita sea la hora en que decidieron bombardearnos con aquello de… “¡escribe comentarios en el código!”. El código bien escrito no necesita comentarios!!!. Un comentario significa que el código no es suficientemente expresivo como para ser leído y mantenido sin comentarios. Cuando sientas la necesidad de añadir un comentario, plantéate reescribir el código primero. No escribas comentarios porque sí. Los comentarios requieren mantenimiento. Si modificas el código y no actualizas sus comentarios, entonces es todavia peor!!!. Los comentarios hay que evitarlos todo lo posible.
Si se trata de un complejo algoritmo matemático, la documentación puede ser un link a un documento científico que lo explica.
Ya lo saben, los comentarios son dañinos, ¡no comentes tu código! ¡hazlo autoexplicativo!

Dedicado a mi buen amigo Adrián 🙂