Regla

Comentario sobre el objetivo (por qué), no la mecánica (qué).
Comentarios que simplemente repite lo el código hace 
proporciona no valor valor y puede quedar obsoleto.

Idiomas admitidos: 45+

Introducción

Los comentarios que simplemente repiten lo que hace el código no aportan claridad adicional y a menudo se desincronizan con la implementación. Cuando los comentarios divergen del código, introducen confusión y ralentizan las revisiones. Los comentarios útiles explican la intención, las suposiciones y el razonamiento detrás de las decisiones. Esto facilita la comprensión y el mantenimiento de la lógica compleja.

Por qué es importante

Implicaciones de seguridad: Los comentarios basados en la intención exponen suposiciones sobre la validación, la confianza en la entrada o el control de acceso que podrían no ser visibles en la implementación.

Impacto en el rendimiento: Los comentarios que aclaran las decisiones relacionadas con el rendimiento ayudan a evitar optimizaciones accidentales o cambios que rompan las características de rendimiento esperadas.

Mantenibilidad del código: Los comentarios centrados en la intención ayudan a los desarrolladores a entender por qué existe una parte del código, reduciendo el tiempo necesario para modificarlo o auditarlo.

Superficie de ataque: Los comentarios claros reducen la posibilidad de usar incorrectamente funciones internas de maneras que introduzcan comportamientos inseguros o expandan la superficie de ataque.

Ejemplos de código

❌ No conforme:

// Loop through users
for (const user of users) {
    // Convert email to lowercase
    user.email = user.email.toLowerCase();
}

Por qué está mal: Estos comentarios repiten lo que el código ya muestra, sin proporcionar contexto sobre la intención o las restricciones.

✅ Conforme:

/**
 * Normalize user emails so downstream permission checks
 * compare consistent lowercase values. Required because
 * external systems may send mixed-case emails.
 */
for (const user of users) {
    user.email = user.email.toLowerCase();
}

Por qué es importante: El comentario explica por qué se requiere la normalización, aclarando la intención y previniendo refactorizaciones incorrectas.

Conclusión

Escribe comentarios que expliquen por qué el código es necesario, no lo que cada línea ya muestra. Describe suposiciones, restricciones y el razonamiento cuando no sean obvios a partir de la implementación. Esto crea una documentación mantenible que sigue siendo útil incluso cuando el código evoluciona.