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:
- Legibilidade: Um código fácil de ler é mais fácil de entender, o que é crucial para a colaboração entre desenvolvedores.
- 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.
- Colaboração: Facilita a colaboração entre desenvolvedores, permitindo que todos possam rapidamente entender a lógica e o fluxo do código.
- 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:
- Nomes significativos
- Funções pequenas e focadas
- Comentários eficientes
- Formatação consistente
- Tratamento adequado de erros
- Estrutura coesa e baixo acoplamento
- Testes automatizados
- Refatoração contínua
- Código simples e direto
- 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:
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- 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
- 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”.
- 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.
- 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.
- 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.
- 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”.
- 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.
![](https://adrianosantostreina.com.br/blog/wp-content/uploads/2024/02/Banner-Hotmart-1.png)
Exemplos de Comentários Eficientes
- Explicação de Decisões de Design
Antes
1 2 3 4 |
// Incrementa o contador contador := contador + 1; |
Depois
1 2 3 4 |
// Incrementa o contador para rastrear o número de tentativas de login falhadas contador := contador + 1; |
Um outro exemplo:
Antes
1 2 3 4 5 6 7 |
// Verifica se o usuário é um administrador if usuario.Role = 'admin' then begin // Permitir acesso end; |
Depois
1 2 3 4 5 6 7 8 |
// Verifica se o usuário é um administrador // Apenas administradores têm permissão para acessar esta seção sensível do sistema if usuario.Role = 'admin' then begin // Permitir acesso end; |
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
1 2 3 4 5 6 |
if total > 1000 then begin AplicarDesconto; end; |
Depois
1 2 3 4 5 6 7 8 |
// Aplica um desconto se o total da compra for maior que 1000 // Esta regra de negócio foi definida pelo departamento de vendas para incentivar compras maiores if total > 1000 then begin AplicarDesconto; end; |
Enfim, não é proibido adicionar comentários ao código, mas o desenvolvedor precisa focar em dois pontos:
- Criar códigos cada vez mais claros que não exijam a presença de um comentário.
- 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