Como estruturei meu primeiro projeto Python que precisava sobreviver mais de uma semana
Scripts são fáceis. Projeto que outros vão ler, que vai ser mantido, que tem módulos e testes — é outra coisa. O que aprendi quando precisei estruturar código para durar além do imediato.
Meu histórico de Python antes de 2018 eram scripts.
Arquivos com duzentas linhas, código linear do topo até o fundo, variáveis com nomes de uma letra, sem nenhuma estrutura além de "funciona quando eu rodo". Para o que esses scripts faziam — automação de tarefas, processamento pontual de arquivo — funcionava.
Quando entrei num projeto de pesquisa que ia durar meses, com código que outras pessoas iam ler, a abordagem de script não funcionou mais.
A primeira coisa que aprendi: módulo não é arquivo de código — é unidade de responsabilidade.
Quando comecei a estruturar o projeto, o instinto era: divide por tipo de coisa. utils.py para funções auxiliares, main.py para o fluxo principal, data.py para tudo de dado.
O problema com divisão por tipo: utils.py vira repositório de tudo que não tem lugar melhor. Em dois meses, tinha 400 linhas e 30 funções com nada em comum além de "não sabia onde colocar".
Aprendi que módulo deve ser dividido por contexto, não por tipo. Funções de limpeza de dado ficam juntas não porque são "utilidades" — mas porque fazem parte do mesmo processo, com as mesmas dependências, e quem muda uma provavelmente vai mudar as outras.
A segunda coisa: funções com nome claro substituem comentário.
# filtra registros onde data está ausente
df = df[df['data'].notna()]
versus
def remove_registros_sem_data(df):
return df[df['data'].notna()]
O primeiro exige comentário para ser entendível. O segundo fala por si. E quando a lógica de filtragem muda — talvez você queira preencher dado faltante em vez de remover — o segundo tem um lugar óbvio para mudar.
A terceira coisa: teste mínimo antes de ser obrigado por outro.
Aprendi a escrever teste quando um bug que eu tinha "corrigido" voltou duas semanas depois porque eu não lembrava que havia tocado naquela função.
Não precisava ser suite completa. O teste mínimo era: os casos que eu sei que precisam funcionar, capturados antes de mudar a função. Quando o test passa, sei que não quebrei o que já funcionava.
A dor que gerou o hábito: ter que explicar para o professor por que o resultado do experimento mudou entre semanas sem ter mudado o dado de entrada. Mudei o código. Não tinha como provar que não havia mudado o comportamento.
A quarta coisa: requirements.txt desde o primeiro dia.
Fui apresentar o projeto no computador do laboratório. Sem as dependências instaladas, nada rodava. E eu não sabia de cabeça quais versões de quais pacotes eu estava usando.
pip freeze > requirements.txt antes de sair do computador de desenvolvimento. Instalação em qualquer outra máquina: pip install -r requirements.txt. Simples. Óbvio depois que você aprende na dor.
Estrutura de projeto não é burocracia. É a diferença entre código que você consegue manter e código que você precisa reescrever quando muda o requisito.
O projeto de pesquisa durou um semestre. O hábito de estruturar código ficou para tudo que vim depois.
Essa semana: seu código atual vai ser entendível por você daqui a três meses — sem precisar de contexto que só existe na sua cabeça agora?