Nombrar identificadores: según su rol, con el vocabulario del dominio, tan largos como su alcance

Objetivo

Quien lee entiende una función o variable a partir del nombre, sin necesidad de leer el cuerpo, y una búsqueda de un término encuentra exactamente sus usos.

Requisitos previos

Un vocabulario compartido del dominio (glosario en el README o en las actas de decisiones); una herramienta que permita renombrar de forma segura en todo el proyecto; la convención de nombres del lenguaje —PEP 8 para Python, «Effective Go» para Go— ya establecida.

Pasos

1. Nombrar según el rol y el significado, no según el tipo o el mecanismo: mahnfrist en lugar de dt2, offene_rechnungen en lugar de liste1, nach_kundin_gruppiert en lugar de dict_result.
2. Longitud según el alcance: el índice de un bucle puede llamarse i; una constante de módulo o una función pública necesita la descripción completa. Effective Go señala que los nombres largos no hacen el código automáticamente más legible, y que a menudo un buen comentario de documentación vale más que un nombre muy largo.
3. Una palabra por concepto en todo el proyecto: laden, holen o lesen, no las tres a la vez; usar los términos del dominio, no los del framework.
4. Los valores booleanos como afirmación (ist_abgelaufen, hat_kinder), las funciones como verbo o frase verbal (berechne_total, sende_erinnerung), las colecciones en plural, y las unidades en el nombre cuando el tipo no las expresa (timeout_ms, betrag_rappen).
5. Evitar las codificaciones: sin prefijos de tipo, sin sufijos como _v2 o _neu que mienten después del siguiente cambio. PEP 8 prohíbe los caracteres únicos l, O e I como nombres de variable, porque en algunas tipografías no se distinguen de 1 y 0.
6. Respetar las convenciones del lenguaje para la visibilidad y la forma: en Go, la mayúscula inicial decide la exportación, y las interfaces con un solo método terminan por convención en -er (Reader, Writer); en Python, los guiones bajos separan palabras y un guion bajo inicial marca lo interno.
7. Si un nombre necesita un comentario para entenderse, renombrar en lugar de comentar. Si mejora la comprensión, renombrar de inmediato, con herramientas, en un commit propio sin otros cambios.

Resultado esperado

Menos comentarios, revisiones más cortas, búsquedas que encuentran exactamente los usos de un término, y código en el que los especialistas del dominio reconocen sus propios términos.

Límites y base de verificación

Los nombres de las API públicas no pueden cambiarse libremente; merecen más cuidado desde la primera vez. Usar identificadores en alemán o en inglés es una decisión de equipo que debe aplicarse de forma consistente; las formas mixtas (getKundin) son lo peor de ambos mundos. Las convenciones provienen de las guías de estilo citadas; no se afirma ninguna medición.