Como documentan cambios del código

[Malenko]

- Esta prohibido documentar lo que hace el código ya que este ha de ser entendible
- Solo se permite comentar con los tags de documentación de código (javadoc, por ejemplo)

Si eliges buenos nombres para tus variables y métodos y haces funciones cortas, el código tendría que ser legible sin ayudas extras. Se estructurado y metódico y tendrás mucho ganado. El meter comentarios "inútiles" que no aportan nada lo único que hacen es generar "ruido" y "volumen" en el fichero de código y provocar que un método que podrías leer en una pantalla sin hacer scroll, tengas que desplazarte para poder leer la función entera (dificultando su entendimiento).

Sobre los comentarios de cambios en el código, es la función de los gestores de control de versión: al hacer el "check-in" has de indicar que se ha modificado y porque.

P.D.: Estas son las normas que uso en un proyecto en le que estoy trabajando actualmente y la verdad es que si programas bien no tienes ningún problema a la hora de leer el código.