# Documentação Interna

#### **Comentários** 

Segundo Robert C. Martin em Código Limpo: Habilidades Práticas do Agile Software,

> “O uso adequado de comentários é compensar nosso fracasso em nos expressar no código.”

Dessa maneira, o **uso de comentários no código deve ser evitado**, visto que, conforme o código passar por manutenção, a tendência é que o comentário fique desatualizado e não condizente com o trecho de código à que se refere.

#### **Comentários que podem ser adicionados:**

##### **Comentários descritivos:**

```PASCAL
// INSS
if (DM_GERACAO.EventosSendoGerados.IndexOf('e301') <> -1) then
begin
	Código Referente ao INSS
end;
```

<p class="callout success">Comentários que complementam o entendimento de uma rotina, mas que não tentam explicar o que está sendo feito no trecho.</p>

---

#### **Comentários que devem ser evitados/removidos:**

##### **Comentários no cabeçalho:**

```PASCAL
{****************************************************************
* Módulo : ArqTeste 											*
* Finalidade : Realizar a exportação de Notas Fiscais 			*
* de Serviços para Prefeitura de São Paulo 						*
* Data : 21/02/2000 											*
* Programador : Fulano da Silva Santos 							*
****************************************************************}
```

<p class="callout danger">Comentários utilizados como cabeçalho que descrevem o que a unit faz, a data de implementação e o programador responsável pela implementação apesar de serem descritivos, muitas vezes não são atualizados conforme o código passa por mudanças. Essas informações podem e devem ser encontradas nas mensagens de versionamento.</p>

---

##### **Comentários referentes à processos passados:**

```PASCAL
// MIGRACAO
// Caso a classe uClass.NumDocs seja utilizada em alguma unit
// a diretiva referente ao arquivo uClass.NumDocs.inc deverá ser acrescentada.
// Ex: Ver units FormPri e Backup, antes do nome da unit;
// No arquivo uClass.NumDocs.inc deverá ser adicionada a diretiva referente ao
// sistema ao qual a classe NumDocs foi adicionada.
```

<p class="callout danger">Comentários como esses não acrescentam informações no entendimento do código e acabam criando uma poluição visual na unit, de modo que, com o passar do tempo a tendência é que esse tipo de comentário seja automaticamente ignorado pelos desenvolvedores. </p>

---

##### **Código comentado:**

```PASCAL
// if ((QMANUT.FieldByName('DiasDireito').AsFloat = 0) or 
//	   (SameText(Trim(QMANUT.FieldByName('DiasDireito').AsString), ''))) and
//     (MessageDialog.Show('Não foi informado os dias de Direito. Deseja Continuar?', 
//		  mtConfirmation, [mbYes, mbNo], 0) = mrNo) then
// begin
// 	 QMANUT.FieldByName('DiasDireito').FocusControl;
// 	 Abort;
// end;
```

<p class="callout danger">Códigos comentados geram confusões no código, além de poluir desnecessariamente a unit, dessa maneira códigos não devem ser comentados e sim removidos. Caso necessário, pode-se visitar o histórico de revisões para acompanhar as alterações do trecho.</p>