Estrutura e Organização de Código: Como Escrever para Humanos (Parte 2)

/ Blog

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.5

Melhor:

def calculate_discount(price):
    return price * 1.5

Dicas:

  • Use nomes descritivos, mesmo que sejam um pouco longos
  • Evite siglas, abreviações obscuras ou nomes genéricos como data, temp, value
  • Para 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.py
  • printers.py
  • senders.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 += 1

Comentário útil:

# avançamos para o próximo item porque o atual foi processado
i += 1

Se 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.py
  • Mantenha 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

👉 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!

Posts relacionados