Python é amplamente reconhecido por sua sintaxe limpa e legível. No entanto, para que projetos ganhem escala e facilitem a manutenção, é fundamental que desenvolvedores adotem padrões consistentes, baseados majoritariamente no PEP 8 (Python Enhancement Proposal 8). Este guia detalha as convenções essenciais para escrever um código profissional e elegante.

1. Recuo e Indentação

A estrutura do Python depende da indentação. A recomendação oficial é utilizar rigorosamente 4 espaços por nível de recuo. O uso de tabulações deve ser evitado, e a mistura de espaços com Tabs reusltará em erros de execução em Python 3.

def calcular_area_retangulo(largura, altura):
    # O recuo de 4 espaços define o corpo da função
    area = largura * altura
    if area > 0:
        print(f"Área calculada: {area}")
    return area

2. Limite de Caracteres e Quebras de Linha

Para garantir que o código seja legível em diferentes editores e resoluções, recomenda-se limitar as linhas a no máximo 79 caracteres. Quando uma expressão for muito longa, prefira utilizar a quebra implícita dentro de parênteses, colchetes ou chaves.

# Uso de parênteses para organizar expressões longas
total_vendas = (vendas_janeiro + vendas_fevereiro + 
                vendas_marco + vendas_abril)

# Estruturas de dados longas também devem ser quebradas
usuarios_ativos = [
    "alice_silva", "bruno_souza", "carlos_eduardo",
    "daniela_lima", "eduardo_oliveira"
]

3. Organização com Linhas em Branco

O uso estratégico de linhas em branco melhora a escaneabilidade do códigoo:

• Utilize duas linhas em branco para separar funções de nível superior e definições de classes.
• Utilize uma linha em branco para separar métodos dentro de uma classe.
• Dentro de funções, use linhas em branco pontualmente para separar blocos de lógica distinta.

class CalculadoraFinanceira:
    def __init__(self, saldo_inicial):
        self.saldo = saldo_inicial

    def adicionar_fundo(self, valor):
        self.saldo += valor


def processar_transacao(conta, valor):
    conta.adicionar_fundo(valor)

4. Padrões de Nomenclatura

Seguir uma convenção de nomes ajuda a identificar o propósito de cada identificador imediatamente:

• Variáveis e Funções: Use snake_case (letras minúsculas separadas por sublinhado). Ex: processar_dados().
• Classes: Use PascalCase (iniciais maiúsculas). Ex: GerenciadorArquivo.
• Constantes: Use UPPER_CASE (todas maiúsculas). Ex: PI_VALOR = 3.14159.

5. Gestão de Importações

As importações devem ser colocadas no topo do arquivo, logo após os comentários iniciais ou docstrings do módulo. Elas devem ser agrupadas na seguinte ordem:

1. Bibliotecas padrão do Python (ex: os, sys).
2. Bibliotecas de terceiros (ex: pandas, requests).
3. Módulos locais do próprio projeto.

import datetime
import json

import requests

from meu_projeto.utils import formatar_data

6. Comentários e Documentação

Comentários devem explicar o "porquê" de algo estar sendo feito, e não o "como" (que deve estar claro no próprio código). Docstrings são usadas para documentar módulos, classes e funções.

def buscar_usuario_por_id(user_id):
    """
    Consulta o banco de dados para localizar um usuário específico.
    
    Args:
        user_id (int): O identificador único do usuário.
    Returns:
        dict: Dados do usuário ou None se não encontrado.
    """
    # Filtra o ID para garantir que seja um inteiro positivo
    if user_id < 1:
        return None
    return banco_de_dados.query(user_id)

7. Espaçamento em Expressões

Evite espaços extras dentro de parênteses, colchetes ou chaves. No entanto, sempre utilize um espaço ao redor de operadores de atribuição (=) e operadores lógicos ou matemáticos (+, -, ==, <).

# Forma correta
resultado = (valor_a + valor_b) * (valor_c - 5)

# Forma incorreta (evite espaços internos)
resultado = ( valor_a + valor_b ) * ( valor_c - 5 )

8. Tratamento de Erros

Ao capturar exceções, seja o mais específico possível. Capturar uma exceção genérica como Exception pode mascarar erros de programação reais (como erros de sintaxe ou de nome de variável).

try:
    configuracao = ler_arquivo_config()
    porta = configuracao['porta']
except FileNotFoundError:
    print("Erro: Arquivo de configuração não encontrado.")
except KeyError:
    print("Erro: A chave 'porta' não existe no arquivo.")

9. Comparações e Boas Práticas

Para verificações de identidade contra objetos únicos como o None, utilize sempre os operadores is ou is not em vez de comparadores de igualdade.

# Recomendado
if resultado is None:
    print("Nenhum dado retornado.")

# Não recomendado
if resultado == None:
    pass