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.

Postmark Image

Speedy emails, satisfied customers

Are delayed transactional emails costing you user satisfaction? Postmark delivers your emails almost instantly, keeping your customers happy and connected.

Sign up

Top comments (0)

The Most Contextual AI Development Assistant

Pieces.app image

Our centralized storage agent works on-device, unifying various developer tools to proactively capture and enrich useful materials, streamline collaboration, and solve complex problems through a contextual understanding of your unique workflow.

👥 Ideal for solo developers, teams, and cross-company projects

Learn more

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay