Code Speaks for Itself: Como Métodos Bem Escritos Tornam Comentários Supérfluos

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:

1. Facilidade de Leitura: O fluxo lógico do método principal se torna evidente, funcionando quase como uma narrativa.

2. Reutilização: Métodos menores e focados podem ser reaproveitados em diferentes contextos.

3. Testabilidade: Testar partes específicas do sistema fica mais fácil com métodos bem definidos.

4. 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).

Code Speaks for Itself em Diferentes Cenários

Essa abordagem não se limita a classes ou serviços. Pode ser aplicada em APIs e até na organização de pacotes e módulos. No entanto, o foco aqui está nos métodos, já que são a unidade básica de clareza em um sistema.

Em Métodos Curtos:

// Antes
public boolean hasMinimumStock(Product product) {
    return product.getStock() >= 10;
}

Embora claro, pode ser melhorado:

public boolean isStockSufficient(Product product) {
    return product.getStock() >= 10;
}

O nome do método agora comunica a intenção: não estamos apenas verificando o estoque, estamos checando se ele é suficiente.

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.

Por fim, métodos bem projetados transformam a experiência de leitura e manutenção do código. Não apenas facilitam a vida do desenvolvedor, mas também servem como documentação viva do sistema. Afinal, o melhor comentário é aquele que nunca precisou ser escrito.