Guía práctica para nombrar variables y funciones sin dolor
Diez recomendaciones que facilitan la lectura y el mantenimiento del código al elegir nombres claros y consistentes.
Los nombres son la primera línea de documentación que deja el autor. Si el lector, sea tu futuro yo o un compañero, no entiende el propósito de una variable o función, el código se vuelve una fuente de frustración. A continuación, diez reglas que he afinado revisando cientos de pull‑request y que pueden aplicarse a cualquier lenguaje.
1. Nombra para el lector, no para ti
El objetivo es que quien lea el fragmento en aislamiento sepa su función. Un ejemplo clásico es x = get_stuff(), que no dice nada. Cambiarlo a user_posts = fetch_posts_for_user(user_id) comunica claramente la intención.
2. Usa distinciones significativas
Evita nombres genéricos como data1, data2 o temp. En su lugar, especifica la diferencia: primeNumbers y evenNumbers en lugar de dos listas sin contexto.
3. Aplica el principio de la menor sorpresa
Una función llamada getUser debe devolver un usuario, no modificarlo. Los prefijos is o has deben reservarse a booleanos; de lo contrario, el código confunde.
4. Ajusta el nivel de abstracción
En una capa de utilidades, buffer está bien; en lógica de negocio, prefiera pending_order a una sola letra p. No sobre‑abstraigas con nombres como thing o item.
5. Evita la desinformación
Nombres demasiado parecidos, como account y accounts, generan colisiones en búsquedas y pueden llevar a errores. En Python, no utilices list como variable, pues oculta el tipo incorporado.
6. Elige nombres pronunciables y buscables
Si no puedes decirlo en voz alta, será complicado comentarlo en una revisión. genymdhms (fecha‑hora) es un anti‑patrón; expirationDate permite buscarlo de forma única con grep.
7. Un solo término por concepto
Defina un vocabulario coherente: si decide usar get para recuperar datos, no mezcle fetch o retrieve. Unificar el término evita dudas sobre diferencias sutiles.
8. Nombra booleanos en forma positivaisFound resulta más legible que notFound. Cuando necesite la negación, basta con !isFound en la condición.
9. No temas renombrar
Durante una revisión, corrija nombres problemáticos. Los IDE modernos hacen que el refactorizado sea seguro y rápido; dejar nombres malos genera deuda técnica.
10. Pregunte cuando dude
Si el nombre no surge con claridad, solicite opinión a un colega o añada un comentario temporal. A menudo, describir la intención ayuda a encontrar la denominación adecuada.
Por qué importa
Un código con nombres claros reduce el tiempo de onboarding, disminuye los bugs y facilita la automatización de refactorizaciones. Adoptar estas prácticas hoy significa menos tiempo perdido en debates de revisión y menos rotura de código en el futuro. La próxima vez que te encuentres frente a data, pregúntate si ese nombre realmente describe lo que representa.
