Estrutura e Organização de Código: Como Escrever para Humanos (Parte 2)
Olá comunidade! ❤️
Este é o segundo artigo sobre melhores práticas de programação.
Se no primeiro artigo falamos sobre os princípios fundamentais das boas práticas de programação, agora vamos colocar esses princípios em ação - na estrutura do código em si.
Código limpo não é apenas sobre lógica correta: é sobre clareza, coesão e organização. Afinal, programar não é só conversar com o computador — é escrever para pessoas. E um código bem organizado economiza horas de leitura, debugging e retrabalho.
Nomes de variáveis e funções: dê significado ao seu código
O nome de uma variável ou função é a primeira e principal forma de documentação. Um bom nome economiza comentários e reduz dúvidas.
Evite:
def f(x):
return x * 1.5Melhor:
def calculate_discount(price):
return price * 1.5Dicas:
Use nomes descritivos, mesmo que sejam um pouco longos
Evite siglas, abreviações obscuras ou nomes genéricos como
data,temp,valuePara funções, use verbos:
get_user(),send_email(),generate_report()
Funções pequenas e coesas
Uma função deve fazer uma coisa só — e bem feita. Se você precisa comentar “essa parte faz X, essa parte faz Y”, talvez seja melhor dividir.
Exemplo antes (função confusa):
def process_order(order):
# valida o pedido
if not order.items:
raise Exception("Pedido vazio")
# salva no banco
save_to_db(order)
# envia e-mail
send_email(order.customer)Exemplo depois (mais limpo e coeso):
def process_order(order):
validate_order(order)
save_order(order)
notify_customer(order)Cada função faz exatamente uma coisa, com um nome claro.
Separação de responsabilidades
Evite funções, arquivos ou módulos que fazem “de tudo um pouco”. Isso dificulta a manutenção, os testes e a reutilização.
Use o princípio da responsabilidade única: cada parte do seu sistema deve ter um único motivo para mudar.
Exemplo de má prática:
# Função que valida, imprime e envia o pedido
def handle_order(order):
if not order.is_valid():
return
print_order(order)
send_order(order)Solução melhor:
Divida as responsabilidades em módulos separados, por exemplo:
validators.pyprinters.pysenders.py
Comentários úteis (e não óbvios)
Comentários são bons, mas devem explicar o porquê, não o que. O que o código faz já deve estar claro pelos nomes.
Comentário inútil:
# incrementa 1
i += 1Comentário útil:
# avançamos para o próximo item porque o atual foi processado
i += 1Se você sente que precisa explicar demais o código, talvez ele precise ser reescrito, não comentado.
Estrutura de pastas e arquivos
Um projeto bem organizado facilita a navegação, leitura e manutenção. Aqui vão boas práticas:
Organização sugerida:
/meu_projeto
├── main.py
├── controllers/
│ └── user_controller.py
├── services/
│ └── user_service.py
├── models/
│ └── user.py
├── tests/
│ └── test_user.py
Dicas:
Separe responsabilidades por função (controllers, services, models)
Não deixe tudo no
main.pyMantenha testes em uma pasta separada e com estrutura espelhada
Refatorando um código mal estruturado
Antes (bagunçado e difícil de manter):
def handle_user(user):
if '@' not in user['email']:
raise Exception('Email inválido')
print(f"Usuário criado: {user['name']}")
with open('log.txt', 'a') as f:
f.write(f"{user['name']} - {user['email']}\n")Depois (mais organizado, testável e reutilizável):
def validate_user_email(user):
if '@' not in user['email']:
raise ValueError('Email inválido')
def log_user_creation(user):
with open('log.txt', 'a') as f:
f.write(f"{user['name']} - {user['email']}\n")
def create_user(user):
validate_user_email(user)
print(f"Usuário criado: {user['name']}")
log_user_creation(user)
Siga-nos no Linkedin e no Instagram e ajude a divulgar nosso conteúdo 🥰
Conclusão: Organize para evoluir
Escrever código limpo não é uma arte inatingível — é o resultado de boas decisões conscientes no dia a dia. Usar bons nomes, escrever funções pequenas e organizadas, separar responsabilidades e estruturar bem seu projeto são atitudes simples que geram ganhos imensos de produtividade e manutenção.
Se o código for bem organizado hoje, ele estará pronto para crescer amanhã.
Leitura recomendada
Arquitetura Limpa: o Guia do Artesão Para Estrutura e Design de Software
CLEAN CODE EM PYTHON: Boas Práticas para Código Limpo e Manutenível
👉 No próximo artigo da série, vamos abordar boas práticas profissionais, como a improtância de testes automatizados, versionamento com Git, refatoração contínua e colaboração em equipe.
Nos vemos na próxima semana!