Boas Práticas de Programação em Python PARTE I

Por Ricardo Costa Val do Rosario

1. PEP 8 e Estilo de Código

•	Siga o guia oficial PEP 8 para formatação e legibilidade

•	Use 4 espaços por nível de indentação (não misture tabs)

•	Limite de 79 caracteres por linha

•	Linhas em branco: 

o	Duas antes de definições de módulos/classes

o	Uma antes de definições de funções internas

Aspecto	Padrão PEP 8

Indentação	4 espaços

Comprimento de linha	Máx. 79 caracteres

Espaços em expressões	a = b + c; não a=b+c

Imports	Standard, terceiros, locais (separados por linha em branco)

2. Convenções de Nomeação

•	Variáveis e funções: snake_case

•	Classes: PascalCase

•	Constantes: UPPER_SNAKE_CASE

•	Módulos e pacotes: nomes curtos em snake_case

Exemplo:

MAX_RETRIES = 5

def calcula_media_notas(notas):
    pass

class ProcessadorDeDados:
    pass

3. Estrutura e Organização de Projeto

•	Mantenha código fonte em um diretório src/

•	Separe testes em tests/

•	Organize módulos por funcionalidade, não por tipo
•	Inclua arquivos de configuração: 
o	pyproject.toml ou setup.py
o	requirements.txt
o	README.md

Estrutura típica:

meu_projeto/
├── src/
│   └── meu_pacote/
│       ├── __init__.py
│       ├── modulo1.py
│       └── modulo2.py
├── tests/
│   └── test_modulo1.py
├── pyproject.toml
├── requirements.txt
└── README.md

4. Comentários e Documentação

•	Documente o porquê do código, não o como

•	Use docstrings para módulos, classes e funções (três aspas)

•	Atualize comentários sempre que o código mudar

def filtra_pares(lista: list[int]) -> list[int]:
  
Retorna uma lista contendo apenas os números pares
presentes na lista de entrada.

return [n for n in lista if n % 2 == 0]

5. Tipagem Estática com Type Hints

•	Aplique anotações de tipo para funções e métodos

•	Auxilia linters e IDEs a detectar erros cedo

from typing import List, Dict

def soma_valores(dados: List[Dict[str, float]]) -> float:
    total = 0.0
    for item in dados:
        total += item["valor"]
    return total

6. Tratamento de Erros e Exceções

•	Use exceções específicas em vez de except: genérico

•	Restrinja o escopo do try/except ao mínimo necessário

•	Utilize finally ou gerenciadores de contexto (with) para liberar recursos
try:

 arquivo = open("dados.csv")
    linhas = arquivo.readlines()
finally:
    arquivo.close()

7. Testes Automatizados

•	Escreva testes unitários com pytest ou unittest

•	Cubra casos de sucesso e falha

•	Use fixtures para preparar e limpar ambientes de teste

import pytest
from meu_pacote.modulo1 import filtra_pares

def test_filtra_pares():
    assert filtra_pares([1,2,3,4]) == [2,4]

8. Gerenciamento de Dependências e Ambientes

•	Isole ambientes com venv ou conda

•	Liste dependências em requirements.txt ou pyproject.toml

•	Congelar versões mínimas necessárias

requirements.txt

numpy>=1.24.0
pandas>=2.0.0