DEV Community

Cover image for Code Speaks for Itself: Métodos Bem Escritos Dispensam Comentários
Glauco Fox
Glauco Fox

Posted on

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

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);
}
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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);
}
Enter fullscreen mode Exit fullscreen mode

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);
}
Enter fullscreen mode Exit fullscreen mode

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);
}
Enter fullscreen mode Exit fullscreen mode

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);
}
Enter fullscreen mode Exit fullscreen mode

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.

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.

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Immerse yourself in a wealth of knowledge with this piece, supported by the inclusive DEV Community—every developer, no matter where they are in their journey, is invited to contribute to our collective wisdom.

A simple “thank you” goes a long way—express your gratitude below in the comments!

Gathering insights enriches our journey on DEV and fortifies our community ties. Did you find this article valuable? Taking a moment to thank the author can have a significant impact.

Okay