Skip to main content

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.
Alguns exemplos de comentários que podem ser utilizados:

Comentários descritivos:

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

Comentários que complementam o entendimento de uma rotina, mas que não tentam explicar o que está sendo feito no trecho.
Alguns exemplos de comentários que devem ser evitados:

Comentários com informações irrelevantes:

{****************************************************************
* 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 							*
****************************************************************}

Ou até mesmo: 

// 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.

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 pelo desenvolvedor. 

Código em forma de comentário:

// 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;

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.

Back to top