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