Regras de padronização

<< Click to Display Table of Contents >>

Navigation:  Novatos >

Regras de padronização

Previous pageReturn to chapter overviewNext page

Formatação de Código Fonte

 

Identação

Para a identação será utilizado 2 espaços. Não salvar “tabs” nos arquivos fonte, a razão disto é que o caracter tab possui diferentes tamanhos em diferentes configurações.

Para desabilitar o uso de tab desligue os parâmetros: Editor properties / General / Use Tab caracter  e  Optimal fill

 

Comentários

Para comentar blocos de comandos use { }

Deve-se usar // para comentários curtos de uma linha.

 

Definidores de Condição

Para definidores de condição use "{" e "}" com o comando sempre em maiúsculas

Estes devem estar identados conforme o exemplo:

 

  if ... then

  begin

    {$IFDEF VER90}

    raise Exception.CreateRes(SError);

    {$ELSE}

    raise Exception.Create(SError);

    {$ENDIF}

  end;

 

Begin..End

O begin sempre aparecerá em sua própria linha:

 

  for I := 0 to 10 do begin // Incorreto, begin na mesma linha do for

 

  for I := 0 to 10 do       // Correto, begin aparece em linha separada

  begin

 

Exemplo com um else:

 

  if some statement = ... then

  begin

    ...

  end

  else

  begin

    SomeOtherStatement;

  end;

 

O “end” sempre deve estar sempre na sua própria linha.

Sempre alinhar os “ends” com seu respectivo begin.

 

Object Pascal

 

Parenteses

Não se deve usar espaços nem depois do abre parênteses e nem depois:

 

  CallProc( AParameter ); // incorrect

  CallProc(AParameter);   // correct

 

Nunca utilize parênteses onde ele não é obrigatório.

 

  if (I = 42then              // incorreto - extra parenteses

  if (I = 42or (J = 42then  // correto - parenteses requeridos

 

Palavras reservadas

 

As palavras reservadas do Delphi devem escritas completamente em minúsculas. (exemplos: string, procedure, function, const, nil, not, then, if, to). Geralmente ficam em negrito na configuração padrão do Delphi.

 

Procedures e Funtions

Devem ser capitalizadas por palavras para facilitar a leitura.

 

  procedure thisisapoorlyformattedroutinename;  // Incorreto

  procedure ThisIsMuchMoreReadableRoutineName;  // correto

 

O nome da rotina deve ser adequado ao seu uso. Se a rotina for executar alguma ação o verbo deve vir a frente:

 

procedure FormatarDisquete;

procedure TrocarUsuario;

 

Rotinas que alteram valor de alguma variável ou campo dever possuir o prefixo SET:

 

procedure SetUserName;

 

Rotinas que capturam valor de alguma variável ou campo dever possuir o prefixo GET:

 

function GetUserName: string;

 

Ordem dos parâmetros

Parâmetros mais genéricos são colocados mais a esquerda. Parâmetros mais específicos à direita. Por exemplo:

 

  function GetEndereco(Planeta, Pais, Estado, Cidade, Rua: string): string;

 

Exceção: O uso do parâmetro Sender (TObject), sempre deve ser o primeiro parâmetro.

 

Parametros conts

Todos os parâmetros que não serão alterados pela rotina devem ser passados com a palavra reservada const para otimização do compilador.

 

Colisão de nomes

Quando usamos uma rotina que o nome colide com outra rotina de outra unit, devemos usar o nome da unit antes do nome da rotina:

 

SysUtils.FindClose(SR);

 

or

 

  Windows.FindClose(Handle);

 

Variáveis

 

Nomeclatura de variaveis

Os nomes de variaveis devem condizer com seu propósito.

Variáveis usadas para controle de loops podem ser um caracter tal como I, J, or K.

 

Variáveis locais

Quando possível as variaveis devem ser inicializadas logo que iniciar a rotina.

 

Variáveis globais

Somente use variáveis globais quando extremamente necessário. Sempre que possível use-as apenas no escopo da unit que será usada. (Após o implementation)

As variáveis globais devem ser inicializadas diretamente na seção “var”.

Devem ser inicializadas com nil, zero ou ‘’; uma razão para isso, é que variáveis deste tipo inicializadas não ocupam espaço em disco a mais, se colocar valor na inicialização, ai sim ocupará espaço em disco.

 

  var

    i: Integer = 0;

 

Tipos

 

Convenção de capitalização

Tipos que nome reservado devem ser mantidas em letras minúsculas. As que possuem tipos ou estruturas da API devem ser colocados em maiúsculas, as demais devem ser identadas:

 

  var

    MyString: string;   // reserved word

    WindowHandle: HWND; // Win32 API type

    I: Integer;         // type identifier introduced in System unit

 

Identação de declarações

Quando for facilitar a leitura pode-se identar as declarações de variáveis conforme exemplo:

 

  var

    MyString    : string;

    WindowHandle: HWND; 

    I, Y, Z     : Integer;

 

Pontos flutuantes

O tipo Real não deve ser mais usado, é mantido para compatibilizar com versões do pascal.

Use Double para propósitos gerais. Extended é um tipo específico para Intel e não é suportado pelo Java. Use o tipo Single somente quando for trabalhar com DLLs de outras linguagens.

 

Tipo enumerados

Os nomes de tipos enumerados devem começar com “T”. Os enumerados (dentro dos parênteses) devem ter como prefixo de 2 a 3 caracteres dos capitais do tipo. Veja exemplo:

 

  TSongType = (stRock, stClassical, stCountry); // iniciam todos com st de SongType

 

As variaveis deste tipo, sempre que possivel devem ter o mesmo nome do tipo só que sem o “T”.

 

Variant e OleVariant

Não use Variant e OleVariant. Só se deve usar quando for trabalhar com programação COM (Automation e ActiveX)

 

Tipos Estruturados

 

Array (Matrizes)

Nomes de matrizes devem indicar a utilidade da mesma. O nome da tipo matriz deve começar sempre com “T”, se for declarado um ponteiro para a matriz este deve possuir o prefixo “P” e deve vir sempre antes da declaração do tipo:

 

  Type

    PValores = ^TValores;

    TValores = array[1..100of Integer;

 

Quando possível a variavel deste tipo deve ter o mesmo nome do tipo sem o “T”.

 

Records

Segue as mesmas regras de array:

 

  Type

    PFuncionario = ^TFuncionario;

    TFuncionario = record

      Nome   : string;

      Salario: Double;

    end;

 

Declarações

 

if

Sempre que possivel use o case ao invés de seqüências de ifs.

Não alinhe mais de 5 declarações.

Não utilize parenteses se estes não forem para deixar o código mais claro ou se não são obrigatórios.

Sempre coloque as condições mais rápidas a direita e as mais lentas para o compilador a esquerda:

 

if (Valor > 0) and (StrToInt(Edit1.Text) = 10) then

 

Quando as condições são extensas, utilize-as em múltiplas linhas alinhadas como no exemplo:

 

  if Condition1 and

     Condition2 and

     Condition3 then

 

Nestes casos a leitura de cima para abaixo é mais fácil do que da esquerda para a direita quando as instruções são mais complexas e extensas.

A cláusula else deve estar sempre alinha com o if correspondente.

 

case

 

Tópicos gerais

Nas maiorias das situações deve-se colocar os valores do case em ordem numérica ou alfabética. Se for um tipo definido pelo usuário coloque-os em ordem em que foram declarados no tipo.

Em alguns casos a ordem case pode ser pela importância ou freqüência.

As ações do case devem ser mantida em apenas uma linha ou não devem exceder 5 linhas de código, para casos mais complexos utilize funções ou procedures separadas. Procedures e funções locais são bem vindas nestes casos.

Tome cuidado especialmente com a identação. A cláusula else deve estar alinhada com o case:

 

  case Condition of

 

    condition:

      begin

        ...

      end;

 

  else // case

    ...

  end;

 

É importante ter um comentário no else para se saber que ele pertence ao case

Formatação

Case segue as mesmas regras de nomeclaturas e indentação já vistas.

 

while

O uso de Exit dentro de while não é aconselhavel.

Todo o código de inicialização de variáveis deve ocorrer logo acima do while.

Qualquer liberação de variaveis (free, destroy) usadas no looping devem ser feitas logo após o while.

 

for

O for deve sempre ser usado no lugar do while quando possível. Quando se sabe o número inicial e o incremento é 1 ou –1.

 

repeat

repeat é similar ao while e segue os mesmos padrões.

 

with

 

Tópicos Gerais

With deve ser utilizado com cuidado. Evite cometer erros ao colocar duas variáveis do mesmo tipo no with como no exemplo: (Isto causa bugs difíceis de encontrar)

with Record1, Record2 do

 

Formatação

A identação e formatação seguem o mesmo padrão visto até o momento.

 

Manipulação de Exceções

 

Tópicos Gerais

A manipulação de exceções é muito util para a liberação de recursos alocados em casos de erros. Para funcionar assim é necessário o uso correto de try..finally.

 

try..finally

Sempre que possivel utilize um try/except para cada alocação de objeto. Este exemplo pode ocasionar algum bug:

  SomeClass1 := TSomeClass.Create

  SomeClass2 := TSomeClass.Create;

  try

    // do some code 

  finally

    SomeClass1.Free;

    SomeClass2.Free;

  end;

Um nova codificação resultaria num código mais seguro e de fácil manutenção:

  SomeClass1 := TSomeClass.Create

  try

    SomeClass2 := TSomeClass.Create;

    try

      // do some code

    finally

      SomeClass2.Free;

    end;

  finally

    SomeClass1.Free;

  end;

 

try..except

Use o try..except somente se deseja executar alguma tarefa quando ocorre uma exceção. Em geral, ao inves de usar try..except para mostrar uma simples mensagem, pode usar o objeto Application para tal. Se deseja mostra uma mensagem use o “raise” para recriar uma exceção.

 

try..except..else

O uso de else com try..except é desencorajado pois ele bloqueia todas as exceções.

 

Classes

 

Nomeclatura e formatação

Os nomes das classes devem identificar o propósito da mesma. Na declaração deve ter o prefixo “T”:

 

  Type

    TCarro = class(TObject)

 

Geralmente a declaração deve combinar com o tipo:

 

  var

    Carro: TCarro;

 

Campos

 

Nomeclatura / Formatação

Classes para campos devem seguir a convenção das variáveis, exceto quando quando possuem o prefixo “F” (para variaveis privadas).

 

Visibilidade

Todos os campos devem ser privados. Para ser acessados externamente utilize propriedades.

 

Declaração

Todos os campos devem ser declarados em linhas separadas:

 

  TNovaClasse = class(TObject)

  private

    fCampo1: Integer;

    fCampo2: Integer;

  end;

 

Métodos

 

Nomeclatura e Formatação

Nomes de métodos seguem a padronização para procedures e funcions.

 

Métodos Static

Use métodos static sempre que não queira que objetos descentes faça a sobreescrita (override) deste mesmo.

 

Métodos Virtual e Dynamic

Use virtual quando deseja que os descendentes sobreescrevam o mesmo. Dynamic devem ser usados somente se existirem muitos descendentes.

Sempre use virtual, utilize dynamic apenas em exceções.

 

Métodos Abstrat

Métodos abstratos devem ser usados apenas para classes que não serão construidas.

 

Métodos de acesso de propriedades

Todos os métodos que possuem acesso a propriedade devem estar na seção private ou protected.

A nomeclatura deve seguir a mesma regra para procedures e functions. O método de leitura da variável deve ter o prefixo Get e para gravação da mesma deve ser Set. O parametro de escrita deve ter como nome Value, e seu tipo deve ser o mesmo da propriedade.

 

  TSomeClass = class(TObject)

  private

    fSomeField: Integer;

  protected

    function GetSomeField: Integer;

    procedure SetSomeField(Value: Integer);

  public

    property SomeField: Integer read GetSomeField write SetSomeField;

  end;

 

Propriedades

 

Nomeclatura e formatação

Propriedades que servem como acesso para campos privados devem ter o mesmo nome do campo privado sem o “F”.

Os nomes de propriedades devem ser substantivos, não verbos. Propriedades representam dados, métodos representam ações.

Propriedade do tipo array devem estar no plural. Propriedades normais devem estar no singular.

 

Arquivos

 

Arquivos do Projeto (dpr)

O nome do projeto deve ser descritivo. Por exemplo, The Delphi 6 Developer's Guide Bug Manager pode ter o nome: DDGBugs.dpr. Um programa para mostrar informações do sistema pode ter o nome SysInfo.dpr.

 

Units

 

Nome das Units

Devem possuir o sufixo Unit. Exemplos: MainUnit.pas, CadastroClienteUnit, ParametrosUnit.

 

Cláusula Uses

As units declaradas deve ser somente as units que serão necessárias pelo código ou declaração de tipos. Remova qualquer unit extra que estiver na seção interface. As units que ficam na cláusula implementation deve ser apenas as necessários para o código abaixo.

 

Seção Interface

Esta seção conterá apenas as declarações de tipos, variáveis, procedures e functions que serão acessadas externamente em qualquer outro caso devem ser declarados na seção implementation.

 

Seção Implementation

Esta seção contém declarações de tipos, variáveis, procedures e functions utilizadas no modo privado para a unit.

 

Seção Initialization

Não coloque muito código de inicialização aqui, isto pode afetar a performance do carregamento.

 

Seção Finalization

Tenha certeza de liberar quaisquer recursos alocados pela initialization aqui.

 

Nome

O nome das units deve ser O MESMO da form porém trocando Form por Unit, exemplo: SobreForm será salva como SobreUnit.

 

Units de uso genérico

O nome da unit deve identificar o propósito. Exemplo: RotinasImpressora.pas. Não utilize nomes genéricos como Rotinas.pas, Funcoes.pas.

 

Units de Componentes

Estas devem estar em uma pasta distinta. Nunca devem ser colocadas na pasta do projeto. O nome da unit deve identificar seu propósito.

 

Cabeçalhos de Units

O uso de informações de cabeçalhos é aconselhavel para todas as units pode conter informações sobre o propósito da unit, data de criação e modificações e autor:

 

{---------------------------------------------------------

  Autor   : Flavio Junior.

  Objetivo: Descentente do TAEDIT, com os poderes do LDBEdit. 

 

  08-10-2001 - Criação

  07-05-2002 - Adicionado suporte para Interbase

 

----------------------------------------------------------}

 

Forms e DataModules

 

Forms

 

Nomeclatura dos Forms

As forms deverão ter um nome descritivo para seu propósito. Sempre deverão der o sufixo Form. Por exemplo, a form de About deverá ter o nome AboutForm. A form principal MainForm. Um exemplo de cadastro de clientes:

 

TCadastroClientesForm = class(TForm)

 

Um exemplo de relatório de férias de funcionários:

 

TRelatorioFeriasFuncionariosForm = class(TForm)

 

Forms auto-create

Deve-se deixar como auto-create somente as forms que tenham uma boa razão para tal, como forms de login, informações exibidas várias vezes, ou a form principal. O restante deve ser criada ao ser usada.

 

Data Modules

Os datamodules do projeto devem ter o prefixo DM:

 

TDMBanco = class(TDataModule)

 

Data module de estoque:

 

TDMEstoque = class(TDataModule)

 

Components

 

Buttons

Os botões devem ter o sufixo Button (btn também é aceitavel):

 

  TLoginPontoForm = class(TForm)

    OkButton: TButton;   // exemplo 1

    CancelaBtn: TButton; // exemplo 2

 

MainMenuItem

Devem possuir o prefixo “Menu” ou apenas “m” para identificá-lo dos outros componentes. Exemplos: mCadastroRua, mReceber

 

Querys & Tables

Devem possuir o sufixo “Qy”  ou “Tb”. Por exemplo:

 

TCadstroClientesForm = class(TForm)

    ClientesQy: TQuery;

    UsuariosTb: TTable;

 

DataSource

Idem a Query e Table, porém o prefixo é “Ds”.

 

DBGrid e StringGrid

Usa-se o sufixo “Grid”, caso há apenas uma grid no form, pode-se usar apenas “Grid”.

 

Labels, Edits, Panels e todos os outros componentes que não estão apresentados acima

Todos os outros componentes seguem o padrão Nome + Classe.

 

TForm1 = class(TForm)

    StatusLabel: TLabel;

    HorarioPanel: TPanel;

 

Exceções

Podem haver algumas exceções para casos em que o nome da classe é muito extensa (geralmente composta por 2 nomes) quando colocada junto com o nome do componente. Neste caso, pode-se abreviar usando apenas a primeira parte do nome da classe. Por exemplo:

 

Classe

Exemplo de Nome

TCheckBox

AceitarCPFBrancoCheck

TTabSheet

ControleUsuariosTab

TComboBox

ArquivoParametrosCombo

TRadioGroup

TipoTEFRadio