Los comentarios pueden ser una herramienta útil para explicar código complejo o el propósito de una sección. Sin embargo, en muchos casos, los comentarios son un síntoma de código poco claro o mal estructurado. En lugar de explicar el código con comentarios, el objetivo debería ser escribir un código autodescriptivo que sea fácil de entender sin necesidad de ellos.

Ejemplo Malo: Uso de Comentarios en Lugar de Nombres Claros

El siguiente ejemplo muestra cómo un nombre poco descriptivo lleva a usar un comentario para explicar algo que debería ser obvio.

Código Malo

1// Esta variable define el color del coche
2int c;

Ejemplo Corregido: Nombres Claros

Beneficios

1. Nombres Claros y Descriptivos: El nombre carColor deja claro el propósito de la variable, eliminando la necesidad del comentario.
2. Mantenibilidad: Si se cambia el propósito de la variable, el nombre se actualiza, evitando comentarios desactualizados.
3. Legibilidad: Cualquier desarrollador que lea el código entiende rápidamente de qué se trata sin necesidad de explicaciones adicionales.

En lugar de usar un comentario, podemos asignar un nombre significativo a la variable para que su propósito sea evidente:

1int carColor;