Nombres de Variables en Python — Reglas, Convenciones y Buenas Prácticas

El nombre de una variable es la etiqueta que Python usa para encontrar un valor en memoria. Elige buenos nombres y tu código se leerá casi como una oración; elige malos nombres y hasta tú tendrás dificultades para entender tu propio script una semana después. Este capítulo cubre las reglas estrictas que Python impone, las convenciones de la comunidad (PEP 8), trampas como la sobreescritura de elementos integrados y los patrones con guiones bajos — todo con ejemplos ejecutables.

Reglas Estrictas — Lo que Python Exige

Antes de las convenciones, existen reglas. Romper cualquiera de ellas produce un SyntaxError o un NameError.

Caracteres permitidos

El nombre de una variable puede contener letras (a-z, A-Z), dígitos (0-9) y guiones bajos (_). Debe comenzar con una letra o un guión bajo — nunca con un dígito. No se permiten espacios, guiones ni caracteres especiales (%, #, @, -).

# Valid names
user_name = "Alice"
_private = 42
value1 = 3.14
MAX_RETRIES = 5

# Invalid names — these all raise SyntaxError
# 1user = "bad"     # starts with a digit
# user-name = "bad" # hyphens are subtraction
# user name = "bad" # space is not allowed

Python distingue mayúsculas de minúsculas

username, Username y USERNAME son tres variables completamente distintas. Esta es una fuente frecuente de errores para los principiantes.

score = 10
Score = 20
SCORE = 30

print(score)   # 10
print(Score)   # 20
print(SCORE)   # 30

Las palabras reservadas no pueden usarse como nombres

Python reserva ciertas palabras para el lenguaje en sí. Usar una como nombre de variable genera un SyntaxError. Puedes listar todas las palabras reservadas con el módulo keyword:

import keyword
print(keyword.kwlist)

Salida (Python 3.12):

['False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await',
 'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except',
 'finally', 'for', 'from', 'global', 'if', 'import', 'in', 'is',
 'lambda', 'nonlocal', 'not', 'or', 'pass', 'raise', 'return', 'try',
 'while', 'with', 'yield']

Errores comunes: usar list, str, int, type o input como nombres de variables — estos son nombres integrados, no palabras reservadas, por lo que Python no generará un SyntaxError, pero silenciosamente sobreescribirás el elemento integrado y obtendrás errores confusos más adelante (consulta Sobreescritura de Elementos Integrados a continuación).

Convenciones de Nomenclatura de PEP 8

PEP 8 es la guía de estilo oficial de Python. Seguirla hace que tu código sea inmediatamente legible para cualquier desarrollador de Python.

Resumen de convenciones

snake_case para variables y funciones

snake_case usa letras minúsculas con guiones bajos entre palabras. Este es el estándar para variables y funciones en Python.

# PEP 8 compliant
first_name = "Alice"
last_name = "Smith"
total_price = 9.99
items_in_cart = 3

# Not PEP 8 (camelCase) — works, but avoid for variables
firstName = "Alice"   # JavaScript style, not Pythonic

ALL_CAPS para constantes

Por convención, un nombre escrito completamente en mayúsculas indica "este valor no debe cambiarse". Python no impone la inmutabilidad, pero la convención es universalmente entendida.

MAX_CONNECTIONS = 100
TIMEOUT_SECONDS = 30
PI = 3.141592653589793

# Using the constant
if current_connections > MAX_CONNECTIONS:
    print("Connection limit reached")

CapWords para clases

Los nombres de clases usan CapWords (también llamado PascalCase): cada palabra comienza con letra mayúscula, sin guiones bajos.

class UserProfile:
    pass

class HttpRequestError(Exception):
    pass

Nombres Descriptivos y Significativos

El mejor nombre de variable le indica al siguiente lector qué representa el valor, no cómo está almacenado. Busca nombres que hagan que una línea de código se lea como una oración.

# Unclear
r = 5
a = 3.14159 * r ** 2

# Clear
radius = 5
circle_area = 3.14159 * radius ** 2

print(circle_area)  # 78.53975

Cuándo los nombres cortos son aceptables

Los nombres de una sola letra (x, y, i, n) son aceptables en contextos breves y bien entendidos:

• Contadores de bucle: for i in range(10):
• Fórmulas matemáticas: y = m * x + b
• Coordenadas: (x, y) o (row, col)

Fuera de estos contextos, prefiere algo descriptivo aunque sea más largo.

Evita abreviaciones innecesarias

Las abreviaciones ahorran pulsaciones de tecla pero reducen la legibilidad. Usa palabras completas a menos que la abreviación sea universalmente conocida.

# Unclear abbreviations
usr_nm = "alice"
tot_amt = 49.95
n_itm = 7

# Clear full names
username = "alice"
total_amount = 49.95
number_of_items = 7

Abreviaciones ampliamente aceptadas que puedes mantener: url, id, http, db, idx, num.

Patrones con Guión Bajo

Python usa guiones bajos en los nombres de variables para comunicar intención. Entender estos patrones te ayudará a leer cualquier código base de Python.

_single_leading — uso interno

Un nombre que comienza con un guión bajo es una señal para otros desarrolladores: "esto es un detalle de implementación; no dependas de ello desde fuera de este módulo o clase." Python no lo impone — es puramente una convención.

class DataLoader:
    def __init__(self, path):
        self.path = path
        self._cache = {}   # internal; not part of the public API

    def load(self):
        if self.path not in self._cache:
            self._cache[self.path] = self._read_file()
        return self._cache[self.path]

    def _read_file(self):
        # "private" helper
        with open(self.path) as f:
            return f.read()

from module import * también omite los nombres que comienzan con _.

__double_leading — name mangling

Dos guiones bajos al inicio activan el name mangling de Python: __attr dentro de la clase Foo se almacena como _Foo__attr. Esto evita sobreescrituras accidentales en subclases.

class Base:
    def __init__(self):
        self.__secret = "hidden"

obj = Base()
# print(obj.__secret)      # AttributeError
print(obj._Base__secret)   # "hidden" — mangled name

Usa el name mangling con moderación; dificulta la depuración.

__dunder__ — métodos especiales

Los nombres rodeados por dobles guiones bajos en ambos lados son los métodos y atributos especiales ("dunder") integrados de Python. Nunca inventes tus propias variables __nombre__ — Python reserva este espacio de nombres.

class Point:
    def __init__(self, x, y):   # called when an instance is created
        self.x = x
        self.y = y

    def __repr__(self):          # called by repr() and in the REPL
        return f"Point({self.x}, {self.y})"

p = Point(3, 4)
print(p)          # Point(3, 4)
print(repr(p))    # Point(3, 4)

_ como variable desechable

Un guión bajo solitario _ se usa por convención como variable "no me importa" cuando debes capturar un valor pero no lo usarás.

# Unpack a tuple but only use two of three values
x, _, z = (1, 2, 3)
print(x, z)  # 1 3

# Loop counter when the index is not needed
for _ in range(5):
    print("hello")

Sobreescritura de Elementos Integrados

Los nombres integrados de Python (list, str, int, dict, type, input, print, id, min, max, sum, open, …) no son palabras reservadas, por lo que Python silenciosamente te permite reutilizarlos como nombres de variables. Esto casi siempre es un error.

# Dangerous — shadows the built-in list type
list = [1, 2, 3]
print(list)           # [1, 2, 3] — seems fine

new = list([4, 5])    # TypeError: 'list' object is not callable

Una vez que asignas list = [1, 2, 3], el nombre list en ese ámbito ya no hace referencia al constructor integrado. La solución es simplemente elegir un nombre diferente.

# Safe
numbers = [1, 2, 3]
more_numbers = list([4, 5])  # list() still works
print(more_numbers)          # [4, 5]

Elementos integrados comunes que se sobreescriben accidentalmente: id, input, type, str, int, float, list, dict, set, tuple, min, max, sum, filter, map, open, print.

Ámbito y Nombres de Variables

El nombre de una variable solo es visible dentro del ámbito donde está definida. Dos variables en ámbitos diferentes pueden compartir el mismo nombre sin conflicto — pero esto puede generar confusión.

total = 0          # module-level variable

def calculate(prices):
    total = 0      # local variable — does NOT overwrite the module-level one
    for price in prices:
        total += price
    return total

result = calculate([10, 20, 30])
print(result)      # 60
print(total)       # 0  — unchanged

Para más información sobre cómo Python resuelve los nombres (la regla LEGB), consulta Python Scope. Para entender las variables globales y la palabra clave global, consulta Variables Globales en Python.

Referencia Rápida

# Hard rules
user1 = "ok"        # letters, digits, underscores — fine
_private = "ok"     # leading underscore — fine
# 1user = "bad"     # SyntaxError: starts with digit
# my-var = "bad"    # SyntaxError: hyphens not allowed

# PEP 8 conventions
snake_case_var = 42           # variables and functions
MAX_VALUE = 100               # constants
# class names use CapWords (PascalCase)

# Underscore patterns
_internal = "internal use"    # single leading: hint "private"
_ = "throwaway"               # lone underscore: discard value

# What to avoid
# list = []      # shadows built-in
# str = "hello"  # shadows built-in
# if = True      # SyntaxError: reserved keyword

Para una introducción más amplia sobre cómo se crean y asignan variables en Python, consulta Python Variables. Para saber cómo agrupar variables relacionadas, consulta Agrupar Variables en Python.

Práctica