Existe uma máxima no Código Limpo que choca muitos desenvolvedores: “O uso adequado de comentários é para compensar a nossa falha em expressar a intenção através do código.” No Delphi 13, com sua sintaxe verbosa e expressiva, temos todas as ferramentas para escrever sistemas que se explicam sozinhos.

1. O Mito do Código Autoexplicativo vs. Comentários Redundantes

Muitos programadores acreditam que “quanto mais comentário, melhor”. No entanto, comentários mentem. O código não. Conforme o sistema evolui e as refatorações ocorrem, os comentários frequentemente são esquecidos e deixam de representar a realidade técnica, tornando-se perigosos.

Quando o Comentário é um “Ruído”

No Delphi, evite comentários que apenas repetem o que o código já diz.

• Dirty: Snippet de códigoi := i + 1; // Incrementa a variável i Pedido.Status := 'P'; // Define status como Pago
• Clean: O código deve ser autoexplicativo através de nomes e tipos:Snippet de códigoInc(ContadorDeItens); Pedido.Status := TStatusPedido.Pago;

2. Comentários Bons vs. Comentários Ruins

Não estamos dizendo que todos os comentários são proibidos, mas eles devem ser a exceção, não a regra.

Comentários Aceitáveis:

1. Comentários Legais: Notas de Copyright ou Licença no topo da Unit.
2. Explicação de Intenção: Quando você toma uma decisão técnica não óbvia (ex: uma otimização de performance complexa ou um contorno de um bug conhecido em uma biblioteca de terceiros).
3. Alertas de Consequências: // Cuidado: Este método leva mais de 30 segundos para processar.
4. TODOs: Para tarefas pendentes, desde que não permaneçam no código por anos.

Comentários Ruins (O que evitar):

1. Código Comentado: Nunca deixe blocos de código antigo comentados. O Git (ou seu sistema de versão) existe para isso. No Delphi 13, código morto polui a visão e gera medo de “será que isso ainda é necessário?”.
2. Diários de Bordo: // 30/12/2025 - Regys alterou para corrigir bug. Use o histórico do commit para rastreabilidade.
3. Marcadores de Fechamento: end; // fim do loop. Se o seu loop é tão longo que você precisa de um marcador para saber onde ele termina, o problema é o tamanho do método (conforme vimos no Artigo 02).

3. Formatação: A Estética do Profissionalismo

A formatação é sobre comunicação. Um código mal formatado envia uma mensagem de desleixo. No Delphi 13, a consistência visual permite que a mente do desenvolvedor foque na lógica e não na estrutura.

Formatação Vertical: A Regra do Jornal

O código deve ser lido como um artigo de jornal. No topo, os conceitos de alto nível (o que a Unit faz). Conforme descemos, os detalhes de implementação (métodos private, lógica interna) aparecem.

• Densidade Vertical: Mantenha linhas relacionadas próximas. Separe conceitos diferentes com uma linha em branco.
• Tamanho dos Arquivos: Evite Units com 5.000 linhas. Tente manter arquivos focados em uma única responsabilidade.

Formatação Horizontal: Identação e Largura

A identação revela a hierarquia. No Delphi, o padrão de 2 espaços é o mais comum e deve ser respeitado rigorosamente.

• Largura da Linha: Evite linhas que exigem scroll horizontal. Uma boa prática é manter o código dentro de um limite de 120 a 140 caracteres.

4. Nuances Técnicas no Delphi 13: O Formatador Automático e XML Documentation

O IDE do Delphi 13 possui um formatador de código integrado (Ctrl + D). Configure-o seguindo um guia de estilo consistente (como o da Embarcadero) e utilize-o sempre antes de cada commit. Isso garante que, independentemente de quem escreveu, o projeto pareça ter sido feito por uma única mão.

XML Documentation: O Equilíbrio

Em vez de comentários soltos, utilize a documentação XML (///). O Delphi 13 usa isso para gerar o Help Insight (o balão que aparece ao passar o mouse sobre um método). Isso é útil para bibliotecas e frameworks, pois fornece documentação rica sem poluir a lógica de implementação.

Snippet de código

/// <summary>
///   Calcula o valor líquido da fatura aplicando descontos e impostos.
/// </summary>
/// <param name="AValorBruto">O valor total original.</param>
/// <returns>Valor pronto para emissão.</returns>
function CalcularLiquido(const AValorBruto: Currency): Currency;

Conclusão: O Código é a Documentação

O objetivo final do Clean Code é que o código seja tão claro que qualquer documentação externa ou comentário seja apenas um complemento, e não uma necessidade para a compreensão. No Delphi 13, formatação e comentários inteligentes são os sinais de um desenvolvedor que se importa com quem lerá seu código no futuro.

Referências

MARTIN, Robert C. Código Limpo: Habilidades práticas do Agile Software. 1. ed. Rio de Janeiro: Alta Books, 2009.

MARTIN, Robert C. Arquitetura Limpa: O guia do artesão para estrutura e design de software. 1. ed. Rio de Janeiro: Alta Books, 2019.

NOGUEIRA, Rodrigo. Delphi e Clean Architecture: Princípios e práticas para software escalável. 2. ed. São Paulo: Editora Engenharia de Software, 2025.