Regla 0x0101h: Los identificadores deben ser descriptivos

0x0101h: Los identificadores deben ser descriptivos¶

Enunciado normativo¶

DEBE elegirse nombres de variables, funciones y tipos que describan con precisión su propósito o su rol en el algoritmo. NO DEBE usarse nombres de una sola letra salvo para índices de iteración de alcance mínimo.

Un identificador descriptivo convierte al código en su propia documentación.

¿Por qué existe esta regla?¶

El problema¶

Un nombre es una promesa sobre el contenido. a, dato o aux no dicen nada: obligan al lector a rastrear todas las apariciones para deducir qué guardan. Cuanto más corto y genérico el nombre, más grande el rango de valores que parece admitir y mayor la probabilidad de reutilizarlo con un significado distinto, que es la raíz de muchos efectos colaterales.

Nombrar bien es una actividad de diseño: obliga a decidir qué representa la variable y, con eso, a descubrir responsabilidades mezcladas.

Consecuencias de violarla¶

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

El estándar C11 no impone semántica a los nombres; solo regula su forma (§6.4.2). La cátedra retoma la tradición de código autodescriptivo y exige nombres que resistan la prueba de leer solo la firma. Esta regla es el fundamento cualitativo de 0x010Bh: Proporcionalidad en longitud de identificadores según su alcance, que fija longitudes mínimas según el alcance.

Alcance y excepciones¶

Cubre variables, funciones, parámetros, campos de struct y typedefs. Los índices de iteración (i, j, k) y contadores locales muy breves (n) se aceptan cuando su alcance son pocas líneas. Coordenadas matemáticas (x, y) y parámetros de fórmulas conocidas también se admiten si el contexto es inequívoco.

Ejemplos exhaustivos¶

❌ Contraejemplo 1 — Nombre que no dice nada¶

int a = obtener_precio();
a = a * 1.21;
printf("%d\n", a);

Por qué falla: a podría ser precio, total o impuesto; el lector no sabe si 1.21 es IVA, descuento o inflación.

❌ Contraejemplo 2 — Nombres genéricos numerados¶

void procesar(int dato1, int dato2, int dato3)
{
    int aux = dato1 + dato2 + dato3;
    printf("%d", aux);
}

Por qué falla: dato1, dato2 y dato3 describen la posición, no el significado; además 0x010Eh: Prescindí de identificadores genéricos con sufijo numérico o afijos (numero1, num_1, n_a, a_n) prohíbe expresamente los sufijos numéricos.

✅ Ejemplo conforme 1 — El nombre revela el rol¶

int precio_base = obtener_precio();
int precio_con_iva = precio_base * IVA_MAS_UNO;
printf("Total: %d\n", precio_con_iva);

Justificación: cada nombre expone la magnitud y su relación; el cálculo se lee sin comentarios.

✅ Ejemplo conforme 2 — Parámetros con dominio explícito¶

static double calcular_promedio(const int edades[], size_t cantidad)
{
    double suma = 0.0;

    for (size_t i = 0; i < cantidad; i++)
    {
        suma += (double)edades[i];
    }

    return cantidad > 0 ? suma / (double)cantidad : 0.0;
}

Justificación: edades, cantidad y suma describen el dato, su tamaño y el acumulador; solo i es breve porque es un índice de alcance mínimo.

⚠️ Casos límite¶

• tmp legítimo: un intercambio de dos líneas puede usar tmp; si sobrevive a más de un bloque, el nombre ya no es aceptable.

• Nombres largos: no son un fin en sí mismo; precio_final_con_descuento es correcto solo si ese es su rol exacto.

• Nombres de terceros: las funciones de la biblioteca estándar (strlen) no se renombran; la regla rige el código propio.

Cómo detectarla¶

Checklist de autocontrol¶

• ¿El nombre describe el rol y no solo el tipo?

• ¿Evité aux, tmp, dato, x1 y variantes numeradas?

• ¿Los índices breves viven en pocas líneas?

• ¿Se entiende la variable sin leer su uso?

Reglas relacionadas¶

• 0x010Bh: Proporcionalidad en longitud de identificadores según su alcance — longitud mínima proporcional al alcance del identificador.

• 0x010Eh: Prescindí de identificadores genéricos con sufijo numérico o afijos (numero1, num_1, n_a, a_n) — prohibición de sufijos numéricos y afijos genéricos.

• 0x0105h: Los nombres de funciones deben usar snake_case estricto en minúsculas — los nombres de función también son identificadores.

• 0x0102h: Los argumentos de función y las variables locales deben usar snake_case en minúsculas — forma snake_case exigida a variables y argumentos.

• 0x0201h: Escribí comentarios que expliquen el ‘porqué’, no el ‘qué’ — el buen nombre reduce la necesidad de comentarios.