← Blog · 15 de abril de 2026 · Equipe ConvertCaseHQ · 7 min de leitura

Convenções de nomes do PEP 8: snake_case para variáveis e funções em Python

O PEP 8 diz que nomes de funções e variáveis devem ser em minúsculas, com as palavras separadas por sublinhados conforme a necessidade de legibilidade. Isso é snake_case: total_price, send_invoice(). As classes usam CapWords (InvoiceSender), as constantes usam maiúsculas com sublinhados (MAX_RETRIES), e os módulos recebem nomes curtos, todos em minúsculas. Isso cobre a maior parte do Python que você vai escrever.

O resto da seção de nomes do PEP 8 é onde mora o detalhe útil: o que significam os sublinhados no início e no fim, como tratar siglas, quais letras isoladas evitar e quando quebrar as regras é a decisão certa. Tudo o que está abaixo foi conferido no próprio PEP 8, e o que aparece entre aspas é a redação do próprio PEP 8, no original em inglês.

As convenções de nomes do PEP 8 num relance

Aqui está quase toda a tabela num módulo pequeno:

# billing.py
MAX_RETRIES = 3
_rate_cache = {}


class PaymentDeclinedError(Exception):
    pass


class InvoiceSender:
    def __init__(self, smtp_host):
        self.smtp_host = smtp_host
        self._attempts = 0

    def send_invoice(self, invoice_id):
        self._attempts += 1
        ...

    @classmethod
    def from_settings(cls, settings):
        return cls(settings["smtp_host"])

Vale conhecer duas linhas mais raras. As variáveis de tipo podem ter o sufixo _co ou _contra para indicar covariância ou contravariância, como em VT_co = TypeVar('VT_co', covariant=True). E as variáveis globais seguem as regras das funções; se um módulo foi pensado para ser usado com from module import *, o PEP 8 recomenda listar os nomes públicos dele em __all__.

Por que snake_case, afinal?

O PEP 8 é de julho de 2001, e os autores listados nele são Guido van Rossum, Barry Warsaw e Alyssa Coghlan. O ponto de partida é uma observação do Guido: o código é lido muito mais vezes do que é escrito. As regras de nomes servem a esse objetivo. Os sublinhados mantêm visíveis os limites entre as palavras até em nomes longos (days_since_last_login), e a divisão entre valores em snake_case e classes em CapWords diz que tipo de coisa um nome é antes mesmo de você procurá-lo. O PEP 8 também define um princípio que prevalece nas APIs públicas: os nomes devem refletir como algo é usado, não como é implementado.

O que significam os sublinhados

O Python não tem uma palavra-chave private, então os sublinhados fazem esse papel por convenção. O PEP 8 reconhece quatro formas:

• _single_leading: um sinal fraco de “internal use” (uso interno). O from module import * ignora esses nomes, mas nada mais impede alguém de usá-los.
• single_trailing_: evita conflito com uma palavra-chave. class_ é melhor do que clss, embora o PEP 8 observe que um sinônimo pode ser ainda melhor.
• __double_leading: dentro de uma classe, isso aciona o name mangling (desfiguração de nomes). O PEP 8 só o sugere para evitar conflitos com atributos em subclasses e admite que algumas pessoas não gostam dele.
• __double_leading_and_trailing__: nomes “magic” (mágicos), como __init__ e __file__. O PEP 8 diz para nunca inventar esses nomes; use só os que estão documentados.

O name mangling surpreende quem o trata como privacidade. É um renomeio, não uma tranca:

class Account:
    def __init__(self):
        self.__pin = "1234"

acct = Account()
acct.__pin            # AttributeError
acct._Account__pin    # "1234": the mangled name still works

Constantes são uma convenção, não uma regra

Escrever um nome em maiúsculas não impede ninguém de reatribuí-lo; o Python executa MAX_RETRIES = 4 sem reclamar. Se você quer que uma ferramenta imponha isso, anote o nome com typing.Final:

from typing import Final

MAX_RETRIES: Final = 3
MAX_RETRIES = 4  # still runs, but mypy reports:
                 # Cannot assign to final name "MAX_RETRIES"

Os membros de enum são o outro lugar onde aparecem maiúsculas. O HOWTO de enum da documentação do Python recomenda enfaticamente nomes de membros em UPPER_CASE, em parte porque enums representam constantes e em parte para evitar conflitos com nomes de métodos: class Color(Enum) com os membros RED e GREEN.

Siglas, letras isoladas e outros casos de borda

Siglas em nomes de classes

O PEP 8 manda pôr em maiúscula todas as letras de uma sigla em CapWords, então HTTPServerError é melhor do que HttpServerError. A biblioteca padrão segue isso em lugares como http.server.HTTPServer e json.JSONDecodeError. Em snake_case, as siglas simplesmente vão para minúsculas: parse_json, http_status.

Isso importa se você renomeia com uma ferramenta. Nosso conversor de maiúsculas e minúsculas transforma processOrder em process_order e HTTPServerError em http_server_error, o que é exatamente o certo para snake_case. Mas a saída em PascalCase escreve as siglas como palavras, então HTTP server error sai como HttpServerError, e você corrigiria as maiúsculas à mão para seguir o PEP 8.

Letras a evitar

Nunca use l (a letra L minúscula), O (a letra O maiúscula) ou I (a letra I maiúscula) como nomes de um único caractere. Em algumas fontes, elas são indistinguíveis de 1 e 0.

mixedCase

Nomes de função em camelCase só são permitidos onde esse já é o estilo predominante, por compatibilidade com versões anteriores. O exemplo do próprio PEP 8 é o módulo threading.

Por que a biblioteca padrão quebra as próprias regras

O PEP 8 admite que a nomenclatura da biblioteca do Python é “a bit of a mess” (uma certa bagunça). Você vai encontrar logging.getLogger() e o assertEqual() do unittest em mixedCase, e classes em minúsculas, como datetime.datetime. Tipos embutidos como list e dict são em minúsculas de propósito: o PEP 8 descreve uma convenção à parte para os embutidos, com CapWords usado só para nomes de exceções e constantes embutidas.

Duas regras do PEP 8 explicam por que esses nomes quase sempre ficam como estão. Primeiro, quando uma biblioteca existente tem um estilo diferente, prefere-se a consistência interna. Segundo, a seção intitulada “A Foolish Consistency is the Hobgoblin of Little Minds” (a consistência tola é o bicho-papão das mentes pequenas): a consistência com o PEP 8 importa, a consistência dentro de um projeto importa mais, e a consistência dentro de um módulo ou de uma função importa mais ainda. Não quebre a compatibilidade com versões anteriores só para cumprir a regra. É por isso que uma classe de teste do unittest ainda define setUp(): o framework chama exatamente esse nome.

Verifique os nomes automaticamente com Ruff ou pep8-naming

Você não precisa revisar os nomes a olho. O plugin pep8-naming, do flake8, os verifica, e o Ruff implementa as mesmas verificações como suas regras N. Dado este arquivo:

maxRetries = 3


class order_processor:
    def processOrder(self, orderId):
        totalPrice = 0
        return totalPrice


class InvalidOrder(Exception):
    pass

O Ruff sinaliza todos os nomes desse arquivo:

$ ruff check --select N --output-format concise orders.py
orders.py:1:1: N816 Variable `maxRetries` in global scope should not be mixedCase
orders.py:4:7: N801 Class name `order_processor` should use CapWords convention
orders.py:5:9: N802 Function name `processOrder` should be lowercase
orders.py:5:28: N803 Argument name `orderId` should be lowercase
orders.py:6:9: N806 Variable `totalPrice` in function should be lowercase
orders.py:10:7: N818 Exception name `InvalidOrder` should be named with an Error suffix
Found 6 errors.

Para ativar as regras no projeto inteiro, acrescente-as ao pyproject.toml:

[tool.ruff.lint]
extend-select = ["N"]

Quando você estiver renomeando um único identificador num arquivo colado, nossa ferramenta Localizar e substituir mostra quantas correspondências alterou, o que é uma checagem rápida antes de colar o resultado de volta. Para uma base de código inteira, use a refatoração de renomear do seu editor, para que as referências em outros arquivos acompanhem.

Um checklist de nomes do PEP 8

• snake_case para funções, métodos, variáveis e argumentos.
• CapWords para classes, com as siglas em maiúsculas e o sufixo Error nas exceções.
• Maiúsculas com sublinhados para constantes de nível de módulo, mais Final se você quiser que um verificador as imponha.
• Nomes de módulo curtos e em minúsculas; evite sublinhados em nomes de pacotes.
• Um sublinhado no início para nomes internos; sublinhados duplos só para evitar conflitos com subclasses.
• Quando uma biblioteca existente usa outro estilo, acompanhe a biblioteca.

Está passando de uma linguagem para outra? Nosso guia rápido para desenvolvedores compara as regras do Python com as de JavaScript, Java, Go, Rust e outras.