Barrapunto

Una opción habitual en Java es usar un revisor de estilo (checkstyle). Normalmente se configura para que una función nunca sobrepase el tamaño de una pantalla estándar, para que la puedas ver completa d eun vistazo. Además, el revisor de estilo también obliga a que todo método tenga un comentario previo (que luego sirve para el JavaDoc). Obliga a que los comentarios terminen con punto y aparte, obliga a que se expliquen los parámetros que se le pasan al método, los valores que devuelve, las excepciones que lanza...

El revisor de estilo también suele obligar a que las variables y los métodos tengan nombres significativos. O al menos a que no sean meras letras.

Además, hay herramientas como Sonar que revsa tu código mirando si todos los métodos tiene pruebas unitarias. Dichas pruebas además de probar el código cada vez que compilas, sirven como ejemplo de uso.

Todo esto hace que mucha gente piense que poner luego comentarios en el interior de la función es innecesario.

Como nota al márgen, tanto Sonar como checkstyle tienen equivalentes en otros lenguajes.

Existen plugins de Sonar para PHP, python, JavaScript, VB6... y más: (donde pone "Additional Languages") [codehaus.org].

A través de PEAR te puedes instalar cosas como PHPdepend, PHPcodesniffer, PHPmd... que pueden ayudar con esas cosas.

Hablo de PHP porque casualmente lo he estado viendo hace poco, supongo que otros lenguajes tendrán también sus cosas.