Regla 

Funciones sin comentarios explicativos.
Las funciones sin comentarios son difíciles de 
entender para otros desarrolladores.

Lenguajes compatibles: 45+

Introducción

Las funciones sin comentarios obligan a los desarrolladores a inferir la intención únicamente a partir de los detalles de implementación. Esto ralentiza las revisiones de código y hace que el mantenimiento sea más propenso a errores. Las explicaciones faltantes también ocultan suposiciones sobre la validación, las expectativas de entrada o las restricciones de seguridad. Una documentación clara reduce el mal uso y ayuda a los equipos a comprender el comportamiento del código más rápidamente.

Por qué es importante

Implicaciones de seguridad: La falta de comentarios oculta suposiciones sobre la validación, las comprobaciones de autorización y las entradas de confianza, lo que facilita el uso indebido y aumenta los riesgos de seguridad.

Impacto en el rendimiento: Las funciones no documentadas pueden utilizarse incorrectamente, provocando operaciones costosas repetidas, análisis innecesarios o una gestión ineficiente de los datos.

Mantenibilidad: Los desarrolladores dedican más tiempo a leer y a realizar ingeniería inversa de la lógica cuando la intención no está documentada, lo que ralentiza la refactorización y la incorporación de nuevos miembros.

Ejemplos de código

❌ No conforme:

// No explanation of expected input or security assumptions
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

Por qué está mal: La función procesa campos relevantes para la seguridad, pero no documenta suposiciones sobre fuentes confiables, estructura esperada o restricciones de entrada.

✅ Conforme:

/**
 * Normalize user data from external input.
 * Expects: `user` contains `id`, `email`, and `roles`.
 * Rejects invalid structures and filters unsafe role values.
 * Ensures normalized identifiers and lowercased email for consistency.
 */
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

Por qué esto es importante: El comentario documenta la intención, las entradas esperadas y las restricciones de seguridad, haciendo que el uso sea predecible y previniendo una integración insegura.

Conclusión

Añade comentarios claros a cualquier función donde la intención, las suposiciones o las restricciones no sean obvias a partir de la firma. Documenta lo que la función espera, lo que devuelve y cualquier comportamiento relevante para la seguridad. Esto mejora la calidad de la revisión, reduce el uso indebido y garantiza un comportamiento predecible en toda la base de código.