Code Speaks for Itself: Métodos Bem Escritos Dispensam Comentários

Glauco Fox — Wed, 20 Nov 2024 04:08:50 +0000

A ideia de que "o código fala por si mesmo" é um princípio poderoso. Mais do que uma regra, é uma filosofia que guia desenvolvedores na escrita de sistemas mais claros, mais fáceis de entender e, consequentemente, mais simples de manter. Esse princípio se alinha perfeitamente com a ideia de Separação de Preocupações (Separation of Concerns) em métodos: cada bloco de lógica deve ser pequeno, focado e tão autoexplicativo que qualquer tentativa de adicionar comentários se torna redundante.

Se você já escreveu um comentário para explicar o que um trecho do seu código faz, provavelmente deveria ter transformado aquele trecho em um método.

Quando o Código Precisa de Comentários

Considere este exemplo:

// Persiste dados de pessoa no banco
if (pessoa != null) {
    pessoaRepository.save(pessoa);
}

O comentário acima explica algo óbvio para o desenvolvedor que conhece o sistema. Porém, ele é um sinal de que podemos dar mais clareza ao código com um pequeno ajuste:

savePessoa(pessoa);

Agora, o que antes era um comentário virou uma função que encapsula a intenção do código, tornando a leitura mais fluida e natural.

Refinando a Intenção dos Métodos

Métodos não devem apenas executar tarefas; eles devem comunicar intenções. Um método bem nomeado é como uma frase clara em uma conversa: deixa pouco espaço para dúvidas.

public void processOrder(Order order) {
    // valida pedido
    if (order.getItems().isEmpty()) {
        throw new IllegalArgumentException("Order cannot be empty.");
    }

    // calcula total do pedido
    double total = 0;
    for (Item item : order.getItems()) {
        total += item.getPrice();
    }

    // notifica o cliente e salva o pedido
    notificationService.notify(order.getCustomer());
    orderRepository.save(order);
}

Nesse exemplo está tudo junto: validação, cálculo, notificação e persistência. Isso torna o método longo e difícil de entender rapidamente.

public void processOrder(Order order) {
    validateOrder(order);
    double total = calculateOrderTotal(order);
    notifyCustomer(order.getCustomer());
    saveOrder(order);
}

private void validateOrder(Order order) {
   if (order.getItems().isEmpty()) {
        throw new IllegalArgumentException("Order cannot be empty.");
    }
}

private double calculateOrderTotal(Order order) {
    return order.getItems().stream()
                .mapToDouble(Item::getPrice)
                .sum();
}

private void notifyCustomer(Customer customer) {
    notificationService.notify(customer);
}

private void saveOrder(Order order) {
    orderRepository.save(order);
}

Ao quebrar o método principal em partes menores e autoexplicativas, removemos a necessidade de comentários e tornamos o fluxo claro. O leitor entende o que acontece em cada passo sem precisar mergulhar nos detalhes imediatamente.

Pequenos Métodos, Grandes Benefícios

A fragmentação de responsabilidades em métodos menores traz diversas vantagens:

Facilidade de Leitura: O fluxo lógico do método principal se torna evidente, funcionando quase como uma narrativa.
Reutilização: Métodos menores e focados podem ser reaproveitados em diferentes contextos.
Testabilidade: Testar partes específicas do sistema fica mais fácil com métodos bem definidos.
Redução de Comentários: Um código bem nomeado elimina a necessidade de explicações adicionais.

Evite Métodos Multitarefa

Um erro comum ao tentar seguir essa abordagem é criar métodos que fazem mais do que deveriam. Isso geralmente acontece quando a descrição do método requer conjunções como "e", "ou", ou palavras como "então".

public void validateAndSaveOrder(Order order) {
    if (order.getItems().isEmpty()) {
        throw new IllegalArgumentException("Order cannot be empty");
    }
    orderRepository.save(order);
}

Esse método não apenas valida o pedido, mas também o salva. Isso mistura responsabilidades distintas e pode complicar mudanças futuras. Em vez disso, divida as responsabilidades:

public void processOrder(Order order) {
    validateOrder(order);
    saveOrder(order);
}

Agora, cada método faz apenas uma coisa. Respeitando o princípio da responsabilidade única (SRP).

A Regra do Comentário

A regra é simples: se você precisa de um comentário para explicar o que uma parte do código faz, transforme-a em um método. Isso mantém o código limpo, autoexplicativo e alinhado com a ideia de que ele deve falar por si mesmo.