Objetivo

Incluir información suficiente en el código de cada programa para que uno mismo y otros programadores entiendan lo que hace y por qué lo hace.

Motivación

Sabiendo que los programadores:

pueden pensar diferente y crear programas muy distintos a un mismo problema,
tienen bagajes y experiencias diversas,
requieren tiempo de formación, de análisis o de ingeniería inversa para conocer un proyecto al que recién se incorporan, o
no tienen por qué recordar el detalle de las decisiones que tomaron en un momento dado sobre su propio código;

resulta evidente que documentar es una buena práctica, especialmente cuando:

hay errores que reparar —todos los programas tienen errores, descubrirlos es cuestión de tiempo–,
hay que extender el programa con nuevas funcionalidades —todos los programas sufren modificaciones, al menos los que tiene éxito–, o
hay que escalarlo o adaptarlo a un nuevo escenario.

Código como documentación

El primer nivel de documentación está en el uso adecuado del propio lenguaje de programación utilizando:

Nombres descriptivos, pronunciables y oportunos para variables, métodos (funciones) y clases (módulos).
Métodos (funciones) breves, que sólo hagan una cosa y la hagan bien.
Clases (módulos) breves, proporcionando API’s simples y consolidadas.
Código limpio y ordenado siguiendo las recomendaciones de formato, tabulaciones y estructura.

Cuanto más claro y descriptivo sea el código, menos comentarios serán necesarios.

Comentarios en el código

Un comentario explica lo que no es evidente, no debe repetir lo que hace el código, sólo aclarar por qué se hace. Puede responder a preguntas como:

¿de qué se encarga una clase (módulo)?
¿para qué sirve un método (función)? (sólo una cosa, y bien)
¿cuál es el uso esperado de un método (función)?, ¿cómo gestiona los errores?
¿para qué se usa una variable?, ¿cuál es su uso esperado?
¿qué algoritmo estamos usando?, ¿de dónde lo hemos sacado?
¿qué limitaciones tiene el algoritmo?, ¿y la implementación?
¿qué se debería mejorar si hubiera tiempo?

¿Dónde poner un comentario?

Siempre:

Al principio de cada clase (módulo).
Al principio de cada método (función).

Por conveniencia (una línea):

Antes de cada variable.
Al principio de un fragmento de código no evidente.
En los bucles.

Recomendaciones

Generar sólo la documentación necesaria, la realmente valiosa, la imprescindible.
Preguntarse al comentar, ¿aporta algo de verdad?, ¿es totalmente necesario?, ¿tiene que ser tan extenso?
Aplicar la regla del Boy Scout, si revisas un código intenta dejarlo mejor de lo que te lo encontraste.
No olvidar revisar los comentarios cuando se modifica un programa, deben estar actualizados.

Herramientas

Es posible usar herramientas para extraer los comentarios del código y generar automáticamente la documentación del software, normalmente en formato HTML, hiperenlazada y navegable.

Algunos lenguajes incorporan sus propias herramientas, como JavaDoc en Java, o rustdoc en Rust, pero hay otros generadores de documentación donde destacan:

Doxygen, para lenguajes como C, Objective-C, C#, PHP, Java, Python; y con extensiones para Perl o Javascript.
Natural Docs, con soporte para múltiples lenguajes y configurable para extenderlo.