Regla 0x0001h: La claridad y prolijidad son de máxima importancia

0x0001h: La claridad y prolijidad son de máxima importancia¶

Enunciado normativo¶

DEBE escribirse el código de modo que cualquier lector competente comprenda su intención sin la ayuda de su autor. NO DEBE recurrirse a compresión de sentencias, abreviaturas crípticas ni trucos sintácticos que sacrifiquen la claridad por la brevedad.

No es una construcción concreta, sino el criterio rector con el que se juzgan todas las demás reglas de sintaxis.

¿Por qué existe esta regla?¶

El problema¶

El código se lee muchas más veces de las que se escribe. Cuando una sentencia concentra varias operaciones, el lector tiene que reconstruir el orden de evaluación y el estado intermedio de cada variable. Ese esfuerzo se paga en cada revisión, en cada sesión de depuración y en cada cambio futuro.

La claridad no es una cuestión estética: se mide por la cantidad de contexto que hay que retener para entender una línea. Una línea que obliga a recordar tres variables y un efecto colateral tiene alta carga cognitiva y, por lo tanto, es propensa al error.

Consecuencias de violarla¶

Fundamento en el estándar y en la cátedra¶

El estándar ISO/IEC 9899:2011 especifica el qué (semántica) pero deja amplios márgenes al cómo: por ejemplo, el orden de evaluación de los operandos no está totalmente determinado (§6.5). La cátedra adopta la claridad como regla cero porque todos los demás códigos de estilo son aplicaciones puntuales de este principio.

Alcance y excepciones¶

Aplica a todo el código entregado, incluidos ejemplos de clase y pruebas. La prolijidad no se negocia con “total, funciona”. Se exceptúan únicamente los fragmentos generados automáticamente por una herramienta, que igualmente deben documentarse como tales.

Ejemplos exhaustivos¶

❌ Contraejemplo 1 — Todo el algoritmo en una línea¶

for (int i=0,j=10;i<j;i++,j--) { printf("%d", i+j); }

Por qué falla: mezcla declaración, dos contadores con direcciones opuestas, la condición y el cuerpo en una sola línea; para saber cuándo termina hay que simular mentalmente la evolución de i y j.

❌ Contraejemplo 2 — Condición con efecto colateral encadenado¶

if ((p = buscar(clave)) != NULL && p->activo && ++intentos < MAX)
    p->usos++;

Por qué falla: tres chequeos, una asignación y un incremento conviven en la misma expresión; si algo sale mal no se sabe si el problema fue la búsqueda, el contador o el acceso al campo.

✅ Ejemplo conforme 1 — Una idea por línea¶

int i = 0;
while (i < limite)
{
    printf("%d", i);
    i++;
}

Justificación: cada línea tiene un único efecto visible y el lector sigue el flujo de arriba hacia abajo sin reconstruir expresiones.

✅ Ejemplo conforme 2 — Condición explicitada paso a paso¶

nodo_t *encontrado = buscar(clave);
bool hay_lugar = intentos < MAX;

if (encontrado != NULL && encontrado->activo && hay_lugar)
{
    encontrado->usos++;
}

Justificación: los subresultados se nombran; la condición final se lee como una frase booleana y cada parte se puede inspeccionar en el depurador.

⚠️ Casos límite¶

• Idioms de una línea: return x > 0 ? x : -x; es compacto, pero la cátedra prohíbe el ternario (0x1007h: No utilizar el operador condicional (ternario) ?:); no es una excepción válida.

• Código generado: tablas y switch gigantes pueden ser ilegibles pero inevitables; se aceptan si están marcados como generados.

• La brevedad no es el objetivo: una función corta y clara es mejor que una línea “ingeniosa”. Si hay que elegir, gana la claridad.

Cómo detectarla¶

Checklist de autocontrol¶

• ¿Puedo explicar cada línea sin mirar la anterior?

• ¿Hay alguna sentencia con más de una operación o efecto lateral?

• ¿Usé nombres completos en vez de abreviaturas de una letra?

• ¿La prolijidad se sostiene aunque el código “funcione”?

Reglas relacionadas¶

• 0x0101h: Los identificadores deben ser descriptivos — nombres descriptivos: la primera herramienta de la claridad.

• 0x0002h: Una declaración de variable por línea — una declaración por línea, aplicación directa de esta norma.

• 0x0003h: Un espacio antes y después de cada operador binario — el espaciado vuelve visible la estructura de las expresiones.

• 0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’ — los comentarios explican el porqué de lo que no es evidente.

• 0x2005h: Cada función debe tener una única responsabilidad (Principio de Responsabilidad Única) — responsabilidad única: la claridad a escala de función.