Comentando linhas de código

Saber fazer uso de comentários em seus programas pode trazer um ganho de produtividade significativo nos seus projetos. Definir um POP (procedimento operacional padrão) que formalize a utilização de comentários para auto-documentação dos módulos implementados é uma prática fundamental adotada pelas equipes de desenvolvimento, fabricas, houses, de software sérias.
Em contra partida, usar comentários para manutenção de lixo, código de teste, código errado, e desatualizado, nos seus fontes é totalmente condenável. Alias, é exatamente isso que acontece quando não se adota uma pratica formalizada para o emprego de comentários.

No Delphi existem alguns tipos de comentários, vejamos:

“//” Barra – barra: comenta uma linha apenas. Exemplo:

procedure TForm1.Edit1Click(Sender: TObject);
begin
   // esse código será executado se vc clickar no Edit1

Form1.Caption := (Sender as TEdit).Text;
   // A linha de código abaixo está comentada
   //Form1.Color := (Sender as TEdit).Color;
end;

Continua ....

“{}” Chaves: Comenta um bloco de código. Ou seja, comentário de várias linhas. Exemplo:

procedure TForm1.FormClick(Sender: TObject);
begin
  {Esse código será executado se o Form1 for clickado.
   Observe que neste exemplo eu posso comentar mais de uma linha
   usando as chaves. }
   if Form1.Height > 100 then
  Form1.Height := Form1.Height - 20;
   ShowMessage('Vc clickou no Form1!! BHUAHAUHA ...');
end;

“(**)” Parêntese + asterístico: Comenta um bloco de código. Ou seja, comentário de várias linhas. Exemplo:

procedure TForm1.FormResize(Sender: TObject);
const
  msgZn = 'O %s foi redimencionado: Altura - %d; Largura - %d';
begin
  (*Esse código será executado cada vêz que
    o Form1 for dimencionado. Observe que neste
    exemplo eu posso comentar mais de uma linha
    usando Parêntese + asterístico. *)
   ShowMessage(Format(msgZn, [Form1.Name, Form1.Height, Form1.Width]));
end;

Qual a diferença entre os comentários de bloco, de mais de uma linha (várias linhas)? Por que eu preciso ter dois tipos diferentes de comentários diferentes que fazem exatamente a mesma coisa? Para que vc possa aninhar comentários. Não é possível aninhar comentários do mesmo tipo. Exemplo:

procedure TForm1.Edit1KeyPress(Sender: TObject; var Key: Char);
begin
   {  Esse exemplo mostra como comentários podem ser aninhados
   A := B; Creeeeeedddooooooo
   // comentei uma linha ...
  }

  (*
     { eu ai fazer este código assim...
       Form1.Caption := Key;
       Mas, mudei de idéia ...
      }
    Mais comentários ... *)

   Form1.Caption := Form1.Caption + Key;
end;

OBS: Lembrando, qualquer coisa que pareça um comentário, mas começa com o caracter “$” (dollar), não é um comentário. É uma diretiva de compilação.

Novidade importante e interessante

O BDS possui suporte aos comentários para documentação “XML”. O Delphi extrai esses comentários da sua unit e salva como XML. A mesma lógica vigente para os comentários anteriormente exemplificados, vale para os seus respectivos comentário para documentação XML.

/// - Comentário de uma única linha.
(*! *) - Comenta um bloco de código. Ou seja, comentário de várias linhas.
{!} - Comenta um bloco de código. Ou seja, comentário de várias linhas.

type
  /// Esse é o Form1 - este é um comentário para documentação XML.
 TForm1 = class(TForm)
   Edit1: TEdit;
    procedure Edit1KeyPress(Sender: TObject; var Key: Char);
    procedure FormResize(Sender: TObject);
   procedure FormClick(Sender: TObject);
   (*! Neste artigo estamos abordando comentários na unit de código.
      Estamos testando também a nova funcionalidade de documentação do BDS.
   !*)
    procedure Edit1Click(Sender: TObject);
  private
{ Private declarations }
  public
{ Public declarations }
end;

O BDS possui uma funcionalidade de documentação das units. Essa funcionalidade é ativada nas opções de projeto: Menu Projetc ► Options ► No item da treeview ► Compiler, em documentation, marque a checkbox “Generate XML documentation”.

Agora, faça um rebuild da aplicação: Menu Projetc ► Build Project (Shift +F9). Veja no diretório onde você salvou o exemplo, dois arquivos novos: “Unit1.xml” e “project1.xml”.

Esse XML pode ser processado por ferramentas que geram documentação nos mais diversos formatos. Além disso, o conteúdo desse arquivo pode ser consumido pelo help do Delphi.

O Doc-O-Matic, por exemplo, é uma excelente ferramenta para gerar documentação a qual poderia ser usada para consumir o XML gerado pelo Delphi para ducumetação.

Ah! Falando em Doc-O-Matic, lembrei de um lance: O comentário para documentação tem que ser feito em áreas específicas da unit. Lembrei disso porque no Doc-O-Matic também funciona dessa forma. Durante a composição dos exemplos para esse artigo percebi que o Delphi não considerou o comentário que fiz dentro do procedimento. Após um breve momento de indignação, lembrei que no Doc-O-Matic os comentários a respeito de métodos, funções e procedimentos deveriam ficar exatamente na linha superior ao corpo do procedimento. Exemplo:

{! Comentário para documentação XML deve ficar aqui! Este é o evento OnClick do Form1}
procedure TForm1.FormClick(Sender: TObject);
begin
 {Esse código será executado se o Form1 for clickado.
   Observe que neste exemplo eu posso comentar mais de uma linha
   usando as chaves. Ess comentário não vai para o XML ...}
  if Form1.Height > 100 then
    Form1.Height := Form1.Height - 20;
  ShowMessage('Vc clickou no Form1!! BHUAHAUHA ...');
end;