Código-Limpo Parte 4: Formatação consistente

Print 🖨 PDF 📄 eBook 📱

A formatação consistente é um dos aspectos mais fundamentais do código-limpo e, embora possa parecer uma questão puramente estética, seu impacto na legibilidade, na manutenibilidade e na colaboração dentro de um projeto de software é profundo. Quando o código é formatado de maneira uniforme, ele se torna mais fácil de ler e compreender, independentemente de quem o escreveu. Isso é crucial em projetos onde múltiplos desenvolvedores colaboram e precisam entender rapidamente o código uns dos outros. Além disso, a formatação consistente ajuda a evitar erros sutis que podem surgir devido à má organização do código.

Robert C. Martin, em “Código-Limpo”, enfatiza que a formatação do código é a primeira coisa que um leitor percebe. Um código bem formatado não apenas demonstra profissionalismo, mas também transmite a mensagem de que o desenvolvedor se preocupa com a qualidade e a clareza do seu trabalho. Este artigo explorará a importância da formatação consistente, as vantagens que ela traz e como implementá-la de forma eficaz no desenvolvimento de software.

Quarto Pilar: Formatação Consistente

A formatação consistente abrange todas as práticas que garantem que o código mantenha um estilo uniforme em todo o projeto. Isso inclui a utilização de convenções de nomeação, indentação, espaçamento, e organização do código. Uma formatação consistente torna o código previsível e fácil de seguir, facilitando a leitura e a compreensão, não apenas para o autor original, mas para qualquer desenvolvedor que trabalhe no projeto.

A Importância da Formatação Consistente

Robert C. Martin, em seu livro “Código-Limpo”, enfatiza que a formatação do código é uma das primeiras coisas que um leitor percebe. Código bem formatado transmite profissionalismo e atenção aos detalhes. Aqui estão algumas razões pelas quais a formatação consistente é importante:

Legibilidade: Código bem formatado é mais fácil de ler e entender. Linhas de código claramente organizadas ajudam os desenvolvedores a seguir a lógica do programa sem esforço adicional.
Colaboração: Em projetos com múltiplos desenvolvedores, a formatação consistente garante que todos sigam o mesmo estilo, tornando a colaboração mais eficiente e reduzindo o tempo gasto em revisões de código devido a diferenças de estilo.
Manutenção: Código formatado de maneira consistente é mais fácil de manter e refatorar. Mudanças podem ser feitas com confiança, sabendo que o estilo e a estrutura serão preservados.
Prevenção de Erros: Código desorganizado pode esconder erros sutis. Uma formatação clara ajuda a evitar problemas como blocos de código mal identificados ou fechamento incorreto de estruturas de controle.

Vantagens da Formatação Consistente

Melhora a Legibilidade: A formatação consistente facilita a leitura do código, permitindo que os desenvolvedores compreendam rapidamente a lógica e a estrutura do programa.
Facilita a Manutenção: Código uniformemente formatado é mais fácil de manter. Alterações e correções podem ser implementadas de maneira mais eficiente.
Promove a Colaboração: Quando todos os membros da equipe seguem as mesmas diretrizes de formatação, a colaboração se torna mais eficaz. O código se torna previsível e compreensível para todos.
Reduz Erros: A formatação clara ajuda a identificar erros rapidamente. Blocos de código bem alinhados e indentados tornam os problemas mais visíveis.

Implementação de Formatação Consistente

Definir Convenções de Codificação: Estabeleça convenções de codificação claras e documentadas para o projeto. Isso inclui regras para nomeação de variáveis, funções, classes, indentação, espaçamento e organização de arquivos.
Utilizar Ferramentas de Formatação: Utilize ferramentas automáticas de formatação de código. O Delphi já possui uma ferramenta interna que pode inclusive ser personalizada, vejamos mais abaixo como fazer isso. Essas ferramentas garantem que o código seja formatado de maneira consistente com base nas convenções definidas.
Revisões de Código Rigorosas: Durante as revisões de código, preste atenção à formatação. Certifique-se de que todos os contribuintes sigam as convenções estabelecidas.
Configurar o Ambiente de Desenvolvimento: Configure o ambiente de desenvolvimento (IDE) para aplicar automaticamente as convenções de formatação. Isso inclui a configuração de regras de formatação e a ativação de plugins que auxiliem na manutenção do estilo do código.
Educação e Treinamento: Garanta que todos os membros da equipe estejam familiarizados com as convenções de formatação e saibam como aplicá-las. Realize sessões de treinamento se necessário.

Exemplos de Formatação Consistente

Indentação Consistente

Antes


if condicao then
begin
  executarAcao;
    outraAcao;
end;

if condicao then

begin

executarAcao;

outraAcao;

end;

Depois


if condicao then
begin
  executarAcao;
  outraAcao;
end;

if condicao then

begin

executarAcao;

outraAcao;

end;

Em um código com apenas duas linhas, talvez pareça algo bobo que não devemos dar importância, porém em codificações mais longas (não ultrapassando os limites de linhas que já comentamos em outro artigo) não se preocupar com a identação e deixar cada linha com identação incosistende, torna o código menos legível.

Explicando um pouco melhor, vejamos.

Indentação Consistente

A indentação consistente é fundamental para a legibilidade do código. Ela ajuda a visualizar a estrutura do código e a hierarquia de blocos de controle, como loops e condições. No Delphi, a ferramenta de formatação permite configurar várias opções para garantir uma indentação uniforme. Vamos dar alguns exemplos e indicar onde podemos configurar a formatação no Delphi. Tudo que indicarmos abaixo é encontrado em Tools > Options > Language > Formatter > Delphi. E uma vez configurado, basta usar Ctrl + D para formatar automaticamente o código.

Configurações de Indentação:

Continuation indent: Defina para 2. Esta configuração adiciona uma indentação adicional para linhas de continuação.
Indent blocks between Begin and End: Defina para True. Isso garante que os blocos de código entre Begin e End sejam corretamente indentados.
Indent case contents: Defina para True. Isso garante que o conteúdo dos casos em uma instrução case seja indentado.
Indent case labels: Defina para True. Isso aplica indentação nas labels dos casos.

Exemplo de Código:

Antes


procedure TForm1.ExemploIndentacao;
var
  i: Integer;
begin
for i := 0 to 10 do
begin
if i mod 2 = 0 then
ShowMessage('Número par: ' + IntToStr(i))
else
ShowMessage('Número ímpar: ' + IntToStr(i));
end;
case i of
0: ShowMessage('Zero');
1: ShowMessage('Um');
else
ShowMessage('Outro número');
end;
end;

procedure TForm1.ExemploIndentacao;

var

i: Integer;

begin

for i := 0 to 10 do

begin

if i mod 2 = 0 then

ShowMessage('Número par: ' + IntToStr(i))

else

ShowMessage('Número ímpar: ' + IntToStr(i));

end;

case i of

0: ShowMessage('Zero');

1: ShowMessage('Um');

else

ShowMessage('Outro número');

end;

Depois


procedure TForm1.ExemploIndentacao;
var
  i: Integer;
begin
  for i := 0 to 10 do
  begin
    if i mod 2 = 0 then
      ShowMessage('Número par: ' + IntToStr(i))
    else
      ShowMessage('Número ímpar: ' + IntToStr(i));
  end;

  case i of
    0: ShowMessage('Zero');
    1: ShowMessage('Um');
  else
    ShowMessage('Outro número');
  end;
end;

procedure TForm1.ExemploIndentacao;

var

i: Integer;

begin

for i := 0 to 10 do

begin

if i mod 2 = 0 then

ShowMessage('Número par: ' + IntToStr(i))

else

ShowMessage('Número ímpar: ' + IntToStr(i));

end;

case i of

0: ShowMessage('Zero');

1: ShowMessage('Um');

else

ShowMessage('Outro número');

end;

Espaçamento Consistente

O espaçamento consistente ajuda a tornar o código mais legível ao definir padrões claros para o uso de espaços ao redor de operadores, palavras-chave e delimitadores. Caso não saiba, não são indicados espaços antes e depois de parênteses, tão pouco “grudar” operadores sem nenhum espaço, isso são apenas alguns exemplos.

Configurações de Espaçamento:

Set spacing around colons: Configure como After only. Define o espaçamento ao redor dos dois pontos.
Set spacing around commas: Configure como After only. Define o espaçamento ao redor das vírgulas.
Set spacing for // comments: Configure como Before and after. Isso assegura que haja espaçamento adequado antes e depois dos comentários.
Set spacing around assignment operators: Configure como Before and after. Define o espaçamento ao redor dos operadores de atribuição.

Exemplo de Código:

Antes:


procedure TForm1.ExemploEspacamento;
var
  x,y: Integer;
begin
  x:=10;
  y:=20;
  if(x>y)then
  begin
    ShowMessage('x é maior que y');
  end else begin
    ShowMessage('x é menor ou igual a y');
  end;
  x:=y+10;
  ShowMessage('Valor de x: ' + IntToStr(x));
end;

procedure TForm1.ExemploEspacamento;

var

x,y: Integer;

begin

x:=10;

y:=20;

if(x>y)then

begin

ShowMessage('x é maior que y');

end else begin

ShowMessage('x é menor ou igual a y');

end;

x:=y+10;

ShowMessage('Valor de x: ' + IntToStr(x));

end;

Depois


procedure TForm1.ExemploEspacamento;
var
  x, y: Integer;
begin
  x := 10;
  y := 20;

  if (x > y) then
  begin
    ShowMessage('x é maior que y');
  end
  else
  begin
    ShowMessage('x é menor ou igual a y');
  end;

  x := y + 10;
  ShowMessage('Valor de x: ' + IntToStr(x));
end;

procedure TForm1.ExemploEspacamento;

var

x, y: Integer;

begin

x := 10;

y := 20;

if (x > y) then

begin

ShowMessage('x é maior que y');

end

else

begin

ShowMessage('x é menor ou igual a y');

end;

x := y + 10;

ShowMessage('Valor de x: ' + IntToStr(x));

end;

Organização Consistente de Código

A organização consistente do código é essencial para garantir que ele seja fácil de navegar e compreender. Isso inclui a estrutura lógica dos arquivos, a ordem das declarações de funções e métodos, e a utilização de seções claras para diferentes partes do código, como variáveis, constantes e implementação de métodos. Um código bem organizado não apenas melhora a legibilidade, mas também facilita a manutenção e a depuração.

Exemplo de Código:

Antes:


procedure TForm1.ButtonClick(Sender: TObject);
begin
  ShowMessage('Botão clicado');
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  // Inicializações
  Label1.Caption := 'Formulário criado';
end;

function TForm1.CalcularSoma(a, b: Integer): Integer;
begin
  Result := a + b;
end;

procedure TForm1.ExibirMensagem(const Mensagem: string);
begin
  ShowMessage(Mensagem);
end;

procedure TForm1.ButtonClick(Sender: TObject);

begin

ShowMessage('Botão clicado');

end;

procedure TForm1.FormCreate(Sender: TObject);

begin

// Inicializações

Label1.Caption := 'Formulário criado';

end;

function TForm1.CalcularSoma(a, b: Integer): Integer;

begin

Result := a + b;

end;

procedure TForm1.ExibirMensagem(const Mensagem: string);

begin

ShowMessage(Mensagem);

end;

Depois:


// Declarações de métodos da classe TForm1
type
  TForm1 = class(TForm)
    Label1: TLabel;
    Button1: TButton;
    procedure FormCreate(Sender: TObject);
    procedure ButtonClick(Sender: TObject);
  private
    function CalcularSoma(a, b: Integer): Integer;
    procedure ExibirMensagem(const Mensagem: string);
  end;

// Implementação dos métodos da classe TForm1
procedure TForm1.FormCreate(Sender: TObject);
begin
  // Inicializações
  Label1.Caption := 'Formulário criado';
end;

procedure TForm1.ButtonClick(Sender: TObject);
var
  Soma: Integer;
begin
  Soma := CalcularSoma(5, 10);
  ExibirMensagem('Botão clicado. Soma: ' + IntToStr(Soma));
end;

function TForm1.CalcularSoma(a, b: Integer): Integer;
begin
  Result := a + b;
end;

procedure TForm1.ExibirMensagem(const Mensagem: string);
begin
  ShowMessage(Mensagem);
end;

// Declarações de métodos da classe TForm1

type

TForm1 = class(TForm)

Label1: TLabel;

Button1: TButton;

procedure FormCreate(Sender: TObject);

procedure ButtonClick(Sender: TObject);

private

function CalcularSoma(a, b: Integer): Integer;

procedure ExibirMensagem(const Mensagem: string);

end;

// Implementação dos métodos da classe TForm1

procedure TForm1.FormCreate(Sender: TObject);

begin

// Inicializações

Label1.Caption := 'Formulário criado';

end;

procedure TForm1.ButtonClick(Sender: TObject);

var

Soma: Integer;

begin

Soma := CalcularSoma(5, 10);

ExibirMensagem('Botão clicado. Soma: ' + IntToStr(Soma));

end;

function TForm1.CalcularSoma(a, b: Integer): Integer;

begin

Result := a + b;

end;

procedure TForm1.ExibirMensagem(const Mensagem: string);

begin

ShowMessage(Mensagem);

end;

Detalhamento das Melhorias:

Declarações e Implementações Separadas: No exemplo “Depois”, as declarações de métodos estão agrupadas na definição da classe TForm1, enquanto as implementações estão separadas. Isso facilita a localização e a leitura das assinaturas dos métodos.
Agrupamento por Funcionalidade: Métodos relacionados, como FormCreate e ButtonClick, são agrupados para mostrar a sequência lógica das operações.
Utilização de Métodos Privados: Métodos auxiliares, como CalcularSoma e ExibirMensagem, são declarados como privados e colocados após os métodos públicos, indicando claramente sua visibilidade e uso interno.
Comentários Explicativos: Adicionar comentários claros para seções do código ajuda a entender rapidamente o propósito de diferentes blocos, como inicializações ou manipulação de eventos.

Perceba também uma sutil mudança. A implementação dos métodos na seção Implementation segue a mesma ordem da declaração em Interface, ou seja,

Primeiro: FormCreate
Segundo: ButtonClick
Terceiro: CalcularSoma
Quarto: ExibirMensagem

Todos são encontrados na mesma ondem que foram declarados lá em cima.

Personalizando a Formatação de Código no Delphi

É claro que nessa série de artigos estamos sendo mais superficiais para que você leitor aprenda o básico e explore as possibilidades mais a seguir. A leitura do livro Código-Limpo de Robert C. Martin fará todo sentido quando resolver comprá-lo e lê-lo. E é importante lembrar que o Delphi te dá total condição de executar todas as tarefas para tornar seu código mais limpo. Uma delas é o formatador automático.

Há bastante tempo atrás existia um plugin chamado Delphi Formatter que implementava a combinação de teclas Ctrl + D para formatação. Você configurava como gostaria que o código fosse ajustado e pressionava Ctrl + D. Não me recordo quando esse plugin foi incorporado ao Delphi, mas a verdade é que muita gente não conhece seu poder. Preparei abaixo algumas dicas para entender melhor e personalizar seu Delphi.

Acessando as Configurações de Formatação

Inicie acessando Tools > Options > Language > Formatter > Delphi. Você vai encontrar várias seções nessa opção, são elas que descrevemos adiante.

Configurando a Indentação

Indentação Geral:
- Continuation indent: Defina para 2. Esta configuração adiciona uma indentação adicional para linhas de continuação.
- Indent blocks between Begin and End: Defina para True. Isso garante que os blocos de código entre Begin e End sejam corretamente indentados.
Indentação em Declarações de Case:
- Indent case contents: Defina para True. Isso garante que o conteúdo dos casos em uma instrução case seja indentado.
- Indent case labels: Defina para True. Isso aplica indentação nas labels dos casos.
Indentação de Labels:
- Indent labels: Configure como Decrease one indent. Isso ajusta a indentação de labels.

Configurando Espaçamentos

Espaçamentos Gerais:
- Set spacing around colons: Configure como After only. Define o espaçamento ao redor dos dois pontos.
- Set spacing around commas: Configure como After only. Define o espaçamento ao redor das vírgulas.
Espaçamento para Comentários:
- Set spacing for // comments: Configure como Before and after. Isso assegura que haja espaçamento adequado antes e depois dos comentários.
Espaçamento para Operadores:
- Set spacing around assignment operators: Configure como Before and after. Define o espaçamento ao redor dos operadores de atribuição.

Configurando Quebras de Linha

Inserção de Quebras de Linha:
- Line break after Begin: Configure como Yes. Isso garante que haja uma quebra de linha após o Begin.
- Line break after Then: Configure como True. Isso assegura que haja uma quebra de linha após o Then.
Quebras de Linha em Funções:
- New line for a function return type: Configure como Yes. Isso força uma nova linha para o tipo de retorno de uma função.
Número de Linhas Vazias:
- Number of empty lines: Defina todas as ocorrências como 1 ou 0, conforme necessário para evitar excesso de linhas vazias.

Configurando Capitalização

Capitalização Geral:
- Capitalization of compiler directives: Configure como UPPER CASE. Isso padroniza as diretivas do compilador em maiúsculas.
- Capitalization of numbers: Configure como UPPER CASE.

Configurando Alinhamento

Casos de Alinhamento:
- Align ‘:=’ in constants: Configure como True. Isso alinha os operadores de atribuição em constantes.
- Align ‘=>’ in type declarations: Configure como True.
Alinhamento Geral:
- Align ‘=’ before type names: Configure como False.

Salvando as Configurações

Depois de ajustar todas as configurações conforme necessário, clique em Save para aplicar as mudanças. Essas configurações ajudarão a garantir que seu código siga as práticas de formatação do código-limpo, tornando-o mais legível e fácil de manter.

É claro que abordei aqui somente as que julgo mais importantes, entretanto as janelas são bem completas e há muitas configurações interessantes a se fazer.

Você sabia que o Delphi possui um guia de Estilo?

Para auxiliar os desenvolvedores a manterem um padrão de codificação claro e consistente, o Delphi oferece o “Delphi’s Object Pascal Style Guide”. Este guia é uma referência essencial que cobre várias práticas recomendadas, desde convenções de nomenclatura até regras de formatação de código. Ele ajuda a garantir que o código escrito por diferentes desenvolvedores seja uniforme, facilitando a leitura, a manutenção e a colaboração em projetos.

O guia de estilo do Delphi aborda tópicos como indentação, espaçamento, organização de código e comentários. Ele fornece diretrizes detalhadas sobre como formatar seu código para maximizar a legibilidade e minimizar erros. Seguir essas diretrizes não só melhora a qualidade do seu código, mas também demonstra um compromisso com as melhores práticas de desenvolvimento. Para acessar o guia completo, visite Delphi’s Object Pascal Style Guide.

Conclusão

A formatação consistente é fundamental para manter o código limpo, legível e fácil de manter. Estabelecer e seguir convenções de formatação, como indentação, espaçamento e organização do código, melhora significativamente a legibilidade e a manutenção do software. Utilizar ferramentas de formatação automáticas no Delphi e seguir guias de estilo, como o “Delphi’s Object Pascal Style Guide”, assegura que todos os desenvolvedores na equipe adotem práticas uniformes, promovendo um ambiente de desenvolvimento mais eficiente e colaborativo. Ao investir na formatação consistente, garantimos um código de alta qualidade e um desenvolvimento mais ágil e produtivo.

Comunidade no Telegram

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

Te vejo na próxima

Adriano Santos

Demais Artigos:

Parte 1: Nomes Significativos
Parte 2: Funções Pequenas
Parte 3: Comentários Eficientes
Parrte 4: Formatação Consistente
Parte 5: Tratamento de Erros
Parte 6: Estrutura de Classes
Parte 7: Testes Automatizados
Parte 8: Refatoração Contínua
Parte 9: Código Simples e Direto
Parte 10: SOLID

Código-Limpo Parte 4: Formatação consistente

Quarto Pilar: Formatação Consistente

A Importância da Formatação Consistente

Vantagens da Formatação Consistente

Implementação de Formatação Consistente

Exemplos de Formatação Consistente

Indentação Consistente

Espaçamento Consistente

Organização Consistente de Código

Personalizando a Formatação de Código no Delphi

Acessando as Configurações de Formatação

Configurando a Indentação

Configurando Espaçamentos

Configurando Quebras de Linha

Configurando Capitalização

Configurando Alinhamento

Salvando as Configurações

Conclusão

Posts Relacionados

Implantando API Horse no EC2 Linux como ServiçoImplantando API Horse no EC2 Linux como Serviço

Delphi Tech Day – DUGRSDelphi Tech Day – DUGRS

Delphi Horse e JWT: Guia CompletoDelphi Horse e JWT: Guia Completo