O que é mais fácil de entender: if Status = 3 then ou if Pedido.Status = TStatusPedido.Enviado then? A resposta parece óbvia, mas o “vício” de usar valores brutos (Magic Numbers) ou strings mágicas ainda assombra muitos projetos Delphi legados. No Código Limpo, cada valor deve ter um nome que revele sua intenção.

No Delphi 13 (Athens), temos recursos de enumeração e constantes tipadas que elevam a legibilidade ao nível de documentação viva.

1. O que são Magic Numbers e por que eles são perigosos?

Magic Numbers são valores numéricos que aparecem do nada no meio do código. Eles são perigosos porque:

1. Não têm significado: O que significa o número 1.05 em um cálculo? É imposto? É comissão?
2. Dificultam a manutenção: Se esse valor mudar, você precisará fazer um “Localizar e Substituir” em todo o projeto, correndo o risco de alterar um 1.05 que não tinha nada a ver com aquele cálculo.

A Abordagem Clean: Constantes Nomeadas

Sempre extraia valores fixos para constantes com nomes claros.

• Dirty: ValorFinal := Valor * 1.05;
• Clean: “`delphi const PERCENTUAL_IMPOSTO_SERVICO = 1.05; … ValorFinal := Valor * PERCENTUAL_IMPOSTO_SERVICO;

2. Enums Modernos: Scoped Enums e Tipagem Forte

No Delphi tradicional, os enums eram “globais” à Unit, o que gerava conflitos de nomes (ex: tsAberto, psAberto). O Delphi 13 incentiva o uso de Scoped Enums através da diretiva {$SCOPEDENUMS ON}.

Por que usar Scoped Enums?

Eles forçam você a usar o nome do tipo antes do valor, o que aumenta drasticamente a legibilidade e evita colisões.

• Dirty: Status := stPago;
• Clean: Status := TStatusPedido.Pago;

3. Substituindo Strings Mágicas por Tipos Enumerados

Muitos desenvolvedores usam Char ou String no banco de dados para representar estados (ex: ‘A’ para Ativo, ‘I’ para Inativo). O erro é levar essa string para dentro da lógica de negócio.

Regra Clean: Converta a string para um Enum assim que o dado entrar no sistema (camada de persistência) e use apenas o Enum na camada de negócio.

• Vantagem: O compilador te avisa se você tentar atribuir um valor inexistente. Com strings, o erro só aparece em tempo de execução.

4. Nuances Técnicas no Delphi 13: Enums com Métodos?

Embora o Delphi não permita métodos diretamente dentro de Enums como o Java, podemos usar Record Helpers para dar “superpoderes” aos nossos Enums e manter o código limpo.

type
  TStatusPedido = (Aberto, Pago, Cancelado);

  TStatusPedidoHelper = record helper for TStatusPedido
    function PodeCancelar: Boolean;
    function ToString: string;
  end;

function TStatusPedidoHelper.PodeCancelar: Boolean;
begin
  Result := Self = TStatusPedido.Aberto;
end;

Uso Clean: if Pedido.Status.PodeCancelar then... – Repare como a lógica de “quem pode cancelar” saiu de dentro de um if complexo e foi para o lugar onde o dado reside.

5. Constantes vs. Recursos (Strings de UI)

Se uma string é exibida para o usuário, ela não deve ser uma constante comum, mas sim um resourcestring. Isso separa a lógica de negócio da localização (tradução) e mantém o código limpo para internacionalização.

Referências

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

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.

TEIXEIRA, Marcello. Delphi High Performance: Build fast Delphi applications using concurrency, parallel programming and memory management. 1. ed. Birmingham: Packt Publishing, 2018.