Olá "Delphianos", estou escrevendo meu primeiro artigo no site, este é o inicio do ciclo de desenvolvimento, este ciclo inicia em padronização de código e vai até o desenvolvimento de um framework para sistemas comerciais. Após o ciclo vou desenvolver um pequeno projeto utilizando todos os recursos citados dentro deste ciclo. Neste artigo estarei passando um manual de padronização de código e documentação, padrão que eu mesmo criei e adotei.

1. Estilos de Capitalização

Existem três tipos de convenções de nomenclatura. São eles: Pascal Case, Camel Case e Upper Case. Em todas as convenções se refere ao uso de maiúsculas ou minúsculas nos nomes. Todas se aplicam a nomes formados por várias palavras.

1.1. Pascal Case

A primeira letra do identificador e as primeiras letras das palavras subseqüentes são maiúsculas.
Exemplo:

BackColor

1.2. Camel Case

A primeira letra da primeira palavra é em minúscula, e as demais palavras subseqüentes iniciam com maiúscula.
Exemplo:

backColor

1.3. Upper Case

Todas as letras são maiúsculas. Usada somente para constantes.
Exemplo:

CHAVE_CRIPTOGRAFIA = String(‘#F$%A&DH’);

2. Tabela de Regras de Capitalização

3. Padrão de Nomenclatura

Nomear corretamente objetos, componentes, arquivos, pastas, enfim, elementos em geral, é muito importante para um bom entendimento do projeto como um todo. Um simples arquivo nomeado errado, ou sem um padrão definido, pode confundir e prejudicar uma futura manutenção. Portanto, questões importantes devem ser consideradas na nomenclatura do projeto:
· Não utilize notação húngara. A notação é útil somente para nomear componentes e, mesmo assim, quando existe a necessidade de identificação facilitada do mesmo;
· Coloque nomes da forma mais clara possível, visando facilitar a compreensão da finalidade;
· Em nomes compostos, faça combinações entre caracteres maiúsculos e minúsculos para PascalCase;
· Utilize abreviações com responsabilidade, e conforme a necessidade;
· Utilize nomes em português;
· Não utilize espaços, acentos, cedilhas, sublinhas ou caracteres especiais, mesmo que o contexto do que está sendo nomeado permita.

3.1. Classes

3.1.1. Classes Objeto

· Nomeie classes objeto com nomes/substantivos;
· Use PascalCase;
· Não use prefixo de classe (por exemplo: CFTP);
· Utilize “T” no início do nome da declaração da classe;
· Não use o caractere de sublinha (_).
Exemplos:

TUsuario = Class; TUsuarioPadrao = TUsuario; TUsuarioBasico = TUsuario;

3.2. Interfaces

· Nomeie interfaces com substantivos ou adjetivos que descrevem o comportamento;
· Use PascalCase;
· Não use o caractere de sublinha (_);
· Coloque a letra I como prefixo, para indicar que o tipo é uma interface;
· Use nomes similares quando definir pares de classes/interfaces, onde a classe é uma implementação padrão das interfaces. O nome deve diferir apenas com a letra I, que é o prefixo do nome da interface.
Exemplos:

IUsuarioBase = Interface TppInterfacedObject = class(TObject, IUnknown)

3.3. Parâmetros

· Use nomes de parâmetros descritivos. Nomes de parâmetros devem ser descritivos o suficiente para que se possa, baseado no nome do parâmetro e seu tipo, determinar o que o parâmetro significa;
· Use PascalCase;
· Use nomes baseados no significado do parâmetro e não baseados no tipo do parâmetro;
· Não use parâmetros reservados (por exemplo: params, args, etc);
· Não use notação Húngara.
Exemplos:

procedure FormataNumero(AValor : Inteiro); function FormataNumero(AValor : Inteiro) : Integer;

3.4. Variáveis

· Nomeie Variáveis usando substantivos;
· Use PascalCase;
· Nunca utilize o caractere de sublinha (_);
· Quando for variável declarada na interface, utilize “F” no início do nome.
Exemplos:

Private FNomeUsuario : String; FSenhaUsuario : String; Public FNomeEmpresa : String; End;

Declaração em métodos:

Procedure ProcessaUsuario(ACodigoUsuario : Integer); var ValorTemporario : Integer; NomeUsuario : String; begin // end;

3.5. Propriedades

· Nomeie propriedades usando substantivos;
· Use PascalCase;
· Considere ter uma propriedade com o mesmo nome do tipo;
· Quando declarar uma propriedade com o mesmo nome do tipo, defina o mesmo tipo da propriedade;
· Não utilize o “T” no início do nome, “T” é utilizado apenas na declaração de tipos.
Exemplos:

private FNomeUsuario : String; public property NomeUsuario : String read FNomeUsuario write FNomeUsuario

3.6. Nome para Arquivos (Units)

· Use PascalCase para nomear arquivos;
· Para formar o nome, utilize o nome da funcionalidade, o tipo da funcionalidade, e o tipo de formulário (form) que você está utilizando (caso esse arquivo seja de um formulário).
Exemplos de formulários:

CategoriaCadastroForm.pas UsuarioListaForm.pas EntradaForm.pas UsuarioPesquisaForm.pas

3.7. Prefixo para Objetos de Interface

· Esses objetos ainda seguem a notação húngara;
· Use as abreviações, nas tabelas a seguir, como prefixo dos objetos;
· Use CamelCase para nomear objetos de interface;
· Utilize a seguinte regra: Três consoantes + Nome do Objeto. Exemplos:
- Query da tabela Banco à qryBanco;
- ClientDataSet da tabela Banco à cdsBanco;
- DataSource ligado ao ClientDataSet à dsrBanco.
Exemplos:

TButton = btnNomeBotao; (Tentar não repetir consoantes). TADOQuery = qryNomeQuery; TSpeedButton = sbtNomeBotao; TActionList = alsNomeActionList;

3.8. Prefixo para Formulários (Form) e Módulos de Dados (DataModule)

· Use CamelCase;
· Form = utilizar “frm” + o nome da funcionalidade;
· DataModule = utilizar “dmd” + o nome da funcionalidade.

Exemplos para DataModule:

dmdClienteProcesso : TDataModule; dmdClienteCadastro : TDataModule; dmdPessoaUsuarioCadastro : TDataModule;

Exemplos para Form:

frmClienteProcesso : TFom; frmClienteCadastro : TForm; frmPessoaUsuarioCadastro : TForm;

4. Endentação

A endentação citada é sobre o número de espaços entre os níveis de tabulação. Utilize como padrão 2 espaços. Este padrão pode ser configurado na janela de opções do Borland Delphi.

Evite escrever linhas com mais de 80 posições entre espaços e caracteres. A idéia é facilitar a compreensão do código e, se possível, visualizar a linha inteira em seu editor de código. Caso alguns trechos de código fiquem muito extensos, poderá ser feita a quebra da linha, entretanto é necessário seguir os seguintes princípios:
· Quebrar a linha após uma vírgula;

· Quebrar a linha após um operador;

· Alinhar a nova linha no início da expressão no mesmo nível da linha anterior.
Exemplos:

calculaArea(expr1, expr2, expr3, expr4, expr5); ou var := a *b / (c - g + f) + 4 * z;

Outra questão importante é a utilização de espaços em branco para endentação. Utilize espaços em branco para endentação, nunca use tabulação!

5. Comentários

Os comentários são muito importantes, tanto para relembrar você como para orientar outra pessoa sobre a manutenção do código fonte. Comente tudo que puder, da seguinte forma:
· Utilize as duas barras “//” para comentar trechos de código;
· Utilize “{}” para comentar blocos.

5.1. Cabeçalho de Arquivos (Units)

Comentários de cabeçalho são importantes para saber quem foi o responsável pelo desenvolvimento e as alterações aplicadas na unit. Portanto:
· Descreva o propósito da unit;
· Coloque o nome do programador responsável pelo desenvolvimento inicial da unit;
· Coloque o nome do analista responsável;
· O item Revisões será utilizado quando for feita uma manutenção na unit;
· Comentários adicionais são importantes caso as alterações efetuadas nessa unit possam afetar alguma outra funcionalidade do sistema.





Exemplo:

(*------------------------------------------------------------------ Propósito da Unit: Programador: Data: ?? Analista Responsável: Revisões: Programador: Data: Descrição da Revisão Comentários adicionais: ------------------------------------------------------------------*)

5.2. Cabeçalho de Métodos

Ao descrever o cabeçalho de um Método:
· Utilize comentário de bloco;
· Não seja detalhista, tente ser objetivo em seu comentário;
· Comente sobre os parâmetros, caso hajam.
Exemplo:

{------------------------------------------------------------------- * Propósito do Método: Exibir uma mensagem de Pergunta utilizando MessageBox * * Utilização dos parâmetros: ATitulo = Titulo da Mensagem (Caption). AMensagem = Mensangem que ira aparecer no corpo do MessageBox. Result = Retorna True caso seja selecionado a opção Sim no MessageBox. * Autor / Data: Everson R. Novka 09/06/2006 *------------------------------------------------------------------} class function TFWMensagem.Pergunta(const ATitulo, AMensagem: String): Boolean; begin Result := (MessageBox(0, PChar(AMensagem), pChar(ATitulo), MB_ICONQUESTION or MB_YESNO or MB_DEFBUTTON2) = idYes); end;

5.3. Comentários dentro de métodos

· Utilize “//” para comentários de apenas um linha;
· Utilize comentário em bloco ( { ... } ) somente em rotinas para comentários de mais de uma linha, a questão visual é fundamental para um melhor entendimento.
Exemplo:

function TfrmMovPontoManual.tbKeyIsDown(const key: integer): boolean; begin //Retorna se a tecla especificada está pressionada. //Gislaine - 26/09/2005 Result := GetKeyState(Key) and 128 > 0; end; }

Conclusão
Este trabalho visou unificar a implementação dos sistemas, seguindo um padrão único de desenvolvimento. Dúvidas e sugestões para melhorias deste documento podem ser encaminhadas para o responsável Everson R. Novka.