Código-Limpo Parte 3: Comentários Eficientes – O Terceiro Pilar do Código-Limpo

Comentários no código são ferramentas poderosas para desenvolvedores. Eles ajudam a esclarecer a lógica, documentar decisões e fornecer contexto adicional que não é imediatamente evidente apenas pela leitura do código. No entanto, a utilização de comentários deve ser feita com cautela e de forma estratégica para evitar problemas como a duplicação de informação ou desatualização. Robert C. Martin, em “Código-Limpo”, enfatiza a importância de escrever comentários eficientes e úteis. Este artigo explora como fazer isso, destacando a importância de bons comentários, suas vantagens e como implementá-los de forma eficaz.

Por que é importante um código-limpo?

Código-limpo é aquele que é fácil de ler, entender e modificar. Manter um código-limpo traz várias vantagens, incluindo:

1. Legibilidade: Um código fácil de ler é mais fácil de entender, o que é crucial para a colaboração entre desenvolvedores.
2. Manutenção: Código claro e bem-estruturado facilita a manutenção e a refatoração, reduzindo o tempo e esforço necessários para essas tarefas.
3. Colaboração: Facilita a colaboração entre desenvolvedores, permitindo que todos possam rapidamente entender a lógica e o fluxo do código.
4. Redução de Erros: Código bem-organizado e legível é menos propenso a erros, pois é mais fácil identificar e corrigir problemas.

Os principais pilares

Os principais pilares do código-limpo são práticas e princípios que guiam os desenvolvedores na criação de código de alta qualidade. Cada pilar aborda um aspecto específico do desenvolvimento de software, contribuindo para a criação de um sistema que é fácil de entender, manter e evoluir. Aqui estão os principais pilares do código-limpo:

1. Nomes significativos
2. Funções pequenas e focadas
3. Comentários eficientes
4. Formatação consistente
5. Tratamento adequado de erros
6. Estrutura coesa e baixo acoplamento
7. Testes automatizados
8. Refatoração contínua
9. Código simples e direto
10. Princípios SOLID

Neste artigo, focaremos no terceiro pilar: Comentários Eficientes.

Terceiro Pilar: Comentários Eficientes

Comentários eficientes são aqueles que realmente agregam valor ao código, explicando o “porquê” por trás das decisões de design e fornecendo contexto adicional. Eles não devem repetir o que o código já diz claramente, mas sim complementar a compreensão do desenvolvedor. Comentários bem escritos ajudam a documentar intenções, explicam raciocínios complexos e facilitam a colaboração.

A Importância de Comentários Eficientes

Robert C. Martin, em seu livro “Código-Limpo”, destaca que comentários são frequentemente usados como um “remédio” para código mal escrito. Ele argumenta que, em vez de usar comentários para explicar o código, os desenvolvedores devem se esforçar para escrever um código que não precise de explicações. No entanto, ele reconhece que há momentos em que comentários são necessários e úteis. Aqui estão algumas situações onde comentários eficientes são cruciais:

1. Decisões de Design Complexas: Quando uma decisão de design é tomada para resolver um problema específico ou para contornar uma limitação, é útil documentar essa decisão com um comentário. Isso ajuda futuros desenvolvedores a entender o contexto e a razão por trás da implementação.
2. Regras de Negócio Específicas: Documentar regras de negócio diretamente no código ajuda a manter o entendimento do domínio dentro do próprio código, facilitando a manutenção e evitando erros.
3. Hacks Temporários: Quando um hack ou uma solução temporária é implementada, é importante adicionar um comentário explicando o motivo e, se possível, um lembrete para refatorar ou revisar essa parte do código posteriormente.
4. Assunções e Dependências: Comentários são úteis para documentar assunções feitas durante a implementação e dependências específicas que não são óbvias apenas pela leitura do código.

Vantagens dos Comentários Eficientes

1. Clareza de Intenção: Comentários eficientes ajudam a explicar a intenção por trás do código, tornando mais fácil para outros desenvolvedores entenderem o propósito de um bloco de código específico.
2. Contexto Adicional: Eles fornecem contexto adicional que pode não ser óbvio apenas pela leitura do código, como o motivo de certas decisões de design.
3. Facilitam a Manutenção: Comentários claros e atualizados tornam a manutenção do código mais fácil, pois os desenvolvedores podem entender rapidamente o que o código faz e por que foi escrito daquela forma.
4. Melhoram a Documentação: Comentários podem servir como uma forma de documentação embutida, ajudando a manter o conhecimento sobre o sistema diretamente no código.

Implementação de Comentários Eficientes

1. Comentar o “Porquê”, Não o “Como”: Explique o raciocínio por trás do código, não apenas o que o código faz. O código já deve ser claro o suficiente para explicar “como” ele faz algo. Por exemplo, em vez de comentar “// incrementa contador”, um comentário eficiente seria “// incrementa contador para rastrear o número de tentativas de login falhadas”.
2. Manter Comentários Atualizados: Comentários desatualizados podem ser mais prejudiciais do que a ausência de comentários. Certifique-se de atualizar os comentários sempre que o código mudar. Comentários desatualizados podem enganar desenvolvedores e levar a mal-entendidos e bugs.
3. Evitar Comentários Óbvios: Comentários que simplesmente descrevem o que o código faz são desnecessários e podem ser evitados. Foque em explicar lógica complexa ou decisões de design não triviais. Por exemplo, um comentário como “// define x para 5” é redundante e desnecessário.
4. Ser Claro e Conciso: Comentários devem ser claros e diretos ao ponto. Evite escrever longos parágrafos quando uma frase curta pode ser suficiente. A clareza e a brevidade ajudam a garantir que os comentários sejam lidos e compreendidos.
5. Usar Comentários para Documentar Regras de Negócio: Utilize comentários para documentar regras de negócio importantes que são implementadas no código. Isso ajuda a manter o entendimento do domínio diretamente no código, como em “// Aplica um desconto se o total da compra for maior que 1000, conforme definido pelo departamento de vendas”.
6. Adicionar “TODO” para Melhorias Futuras: Use comentários para marcar partes do código que precisam de melhorias futuras ou refatoração com a tag “TODO”. Isso serve como um lembrete visível para desenvolvedores futuros.

Exemplos de Comentários Eficientes

1. Explicação de Decisões de Design

Antes

Depois

Um outro exemplo:

Antes

Depois

Parece bobo, mas perceba que no primeiro exemplo é bastante óbvio que é um incremento de contador, entretanto ao ver o comentário atualizado, percebemos que é um propósito no comentário, explicar o porque da variável e seu incremento.

No segundo exemplo tempos uma situação semelhamente. Percebemos claramente que o sistema está validando se o usuário é um administrador, ok, mas por quê? Na atualização entendemos que há um motivo para isso acontecer.

3. Documentação de Regras de Negócio

No exemplo a seguir, implementamos um comentário que explica o porque da condicional if total > 1000 then, e que adicona maior clareza.

Antes

Depois

Enfim, não é proibido adicionar comentários ao código, mas o desenvolvedor precisa focar em dois pontos:

1. Criar códigos cada vez mais claros que não exijam a presença de um comentário.
2. Na impossibilidade, que o comentário seja realmente necessário e claro.

Conclusão

Comentários eficientes são uma parte vital do código-limpo. Eles fornecem clareza, contexto e ajudam a documentar o raciocínio por trás do código. Ao implementar comentários eficientes, os desenvolvedores podem melhorar significativamente a legibilidade e a manutenibilidade do código, facilitando a colaboração e garantindo que o conhecimento sobre o sistema seja preservado. Investir tempo para escrever bons comentários é uma prática que paga dividendos a longo prazo, resultando em um código mais robusto e sustentável. No próximo artigo, exploraremos o quarto pilar do código-limpo: Formatação Consistente.

Comunidade no Telegram

🚀Comente no campo abaixo 👇👇👇 o que achou e qual sua dúvida.

Te vejo na próxima

Adriano Santos