Nomes de Variáveis em Python — Regras, Convenções e Boas Práticas

O nome de uma variável é o rótulo que Python usa para encontrar um valor na memória. Escolha bons nomes e seu código ficará quase como uma frase; escolha nomes ruins e até você mesmo terá dificuldade em entender o próprio script uma semana depois. Este capítulo aborda as regras rígidas que Python impõe, as convenções que a comunidade segue (PEP 8), armadilhas como o sombreamento de built-ins, e padrões especiais com underscores — tudo com exemplos executáveis.

Regras Obrigatórias — O que Python Exige

Antes das convenções, existem as regras. Violar qualquer uma delas resulta em SyntaxError ou NameError.

Caracteres permitidos

Um nome de variável pode conter letras (a-z, A-Z), dígitos (0-9) e underscores (_). Ele deve começar com uma letra ou um underscore — nunca com um dígito. Espaços, hífens ou caracteres especiais (%, #, @, -) não são permitidos.

# 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 diferencia maiúsculas de minúsculas

username, Username e USERNAME são três variáveis completamente diferentes. Essa é uma fonte frequente de erros para iniciantes.

score = 10
Score = 20
SCORE = 30

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

Palavras-chave reservadas não podem ser usadas como nomes

Python reserva certas palavras para a própria linguagem. Usar uma delas como nome de variável gera SyntaxError. Você pode listar todas as palavras-chave reservadas com o módulo keyword:

import keyword
print(keyword.kwlist)

Saída (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']

Erros comuns: usar list, str, int, type ou input como nomes de variáveis — esses são nomes built-in, não palavras-chave reservadas, então Python não gerará SyntaxError, mas você silenciosamente irá sombrear o built-in e obterá erros confusos mais tarde (veja Sombreando Built-ins abaixo).

Convenções de Nomenclatura PEP 8

PEP 8 é o guia de estilo oficial de Python. Segui-lo torna seu código imediatamente legível para qualquer desenvolvedor Python.

Resumo das convenções

snake_case para variáveis e funções

snake_case usa todas as letras em minúsculas com underscores entre as palavras. Este é o padrão para variáveis e funções em 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 convenção, um nome escrito em letras maiúsculas sinaliza "este valor não deve ser alterado". Python não impõe imutabilidade, mas a convenção é universalmente compreendida.

MAX_CONNECTIONS = 100
TIMEOUT_SECONDS = 30
PI = 3.141592653589793

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

CapWords para classes

Nomes de classes usam CapWords (também chamado de PascalCase): cada palavra começa com letra maiúscula, sem underscores.

class UserProfile:
    pass

class HttpRequestError(Exception):
    pass

Nomes Descritivos e Significativos

O melhor nome de variável informa ao próximo leitor o que o valor representa, não como está armazenado. Busque nomes que façam uma linha de código lida como uma frase.

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

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

print(circle_area)  # 78.53975

Quando nomes curtos são aceitáveis

Nomes de uma letra (x, y, i, n) são aceitáveis em contextos restritos e bem compreendidos:

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

Fora desses contextos, prefira algo descritivo mesmo que seja mais longo.

Evite abreviações desnecessárias

Abreviações economizam teclas, mas custam legibilidade. Use palavras completas a menos que a abreviação seja universalmente conhecida.

# 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

Abreviações amplamente aceitas que podem ser mantidas: url, id, http, db, idx, num.

Padrões com Underscore

Python usa underscores em nomes de variáveis para comunicar intenção. Entender esses padrões ajuda você a ler qualquer base de código Python.

_single_leading — uso interno

Um nome que começa com um underscore é um sinal para outros desenvolvedores: "este é um detalhe de implementação; não dependa dele de fora deste módulo ou classe." Python não impõe isso — é puramente uma convenção.

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 * também ignora nomes que começam com _.

__double_leading — name mangling

Dois underscores iniciais ativam o name mangling do Python: __attr dentro da classe Foo é armazenado como _Foo__attr. Isso evita sobrescritas acidentais em subclasses.

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

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

Use name mangling com moderação; ele torna a depuração mais difícil.

__dunder__ — métodos especiais

Nomes cercados por underscores duplos em ambos os lados são os métodos e atributos especiais ("dunder") integrados do Python. Nunca invente suas próprias variáveis __name__ — Python reserva esse espaço de nomes.

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 descarte

Um underscore solitário _ é usado por convenção como variável "não me importa" quando você precisa capturar um valor, mas não vai usá-lo.

# 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")

Sombreando Built-ins

Os nomes built-in do Python (list, str, int, dict, type, input, print, id, min, max, sum, open, …) não são palavras-chave, então Python silenciosamente permite reutilizá-los como nomes de variáveis. Isso é quase sempre um bug.

# 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

Depois de atribuir list = [1, 2, 3], o nome list naquele escopo não se refere mais ao construtor built-in. A correção é simplesmente escolher um nome diferente.

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

Built-ins comuns que são acidentalmente sombreados: id, input, type, str, int, float, list, dict, set, tuple, min, max, sum, filter, map, open, print.

Escopo e Nomes de Variáveis

O nome de uma variável só é visível dentro do escopo onde ela é definida. Duas variáveis em escopos diferentes podem compartilhar o mesmo nome sem conflito — mas isso pode gerar confusão.

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 mais informações sobre como Python resolve nomes (a regra LEGB), veja Python Scope. Para entender variáveis globais e a palavra-chave global, veja Global Variables in Python.

Referência 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 uma introdução mais ampla sobre como variáveis são criadas e atribuídas em Python, veja Python Variables. Para aprender a agrupar variáveis relacionadas, veja Group Variables in Python.

Prática