Clean Code: Capítulo 4

TLTR: La mayoría de las veces los comentarios son luces de neón parpadeantes con forma de flecha que señalan código inexpresivo.

Un comentario — suponiendo que se ha usado correctamente — sólo está compensando la falta de expresividad de nuestro código. En ese sentido, un comentario simboliza un error que hemos cometido, pues no hemos sido capaces de expresar la intención del código y ha sido necesario explicarla.

Además, el código cambia a medida que pasa el tiempo, y muy a menudo los comentarios quedan obsoletos. El tiempo que se dedicaría a actualizar los comentarios cuando cambia el código se podría invertir en escribir un código más claro.

Sin embargo, los comentarios sí pueden ser útiles en ciertos casos:

• Proporcionaran información legal (copyright, autores, …), aunque se debería considerar añadir esta información en otro sitio
• Justificar una decisión que se tomado respecto al código
• Hacer aclaraciones sobre funciones de librerías externas
• Advertir de algo a otras personas que vayan a usar ese código
• Comentarios “TO-DO”
• Señalar la importancia de algo