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