padrao codigo

Padrão de Código

Home > Guia de contribuição do PascalRAL > Padrão de Código

• Todas as units precisam ser concisas e referenciar um escopo, não existe necessidade de ter uma unit pra cada classe.

• Os uses são organizados por grupo de escopo, seguindo as condições:

  • Diretivas de compilação: caso a unit dependa de outra baseada em uma condição específica, essas diretivas sempre vêm primeiro na seção uses. Caso a diretiva seja usada, precisa importar a PascalRAL.inc que contém o mapeamento das diretivas mais comuns. Caso a diretiva que você precisa não esteja inclusa lá, defina lá para usar na classe, garantindo que não seja uma redundância de outra diretiva existente.
  • Units nativas da IDE: dependências presentes em todas as IDEs, tais como Classes, SysUtils, System...
  • Units da dependência: units necessárias da dependência. Ex: ZQuery, ZComponent...
  • Units do projeto: units presentes nos fontes do projeto RAL. Ex: RALTools, RALTypes...

• As classes precisam ser documentadas usando a notação comum de 3 barras /// seguidas da descrição resumida do método no idioma padrão Inglês americano enUS.

• As seções internas das classes são organizadas em:

  • 1. Private
  • 2. Protected
  • 3. Public
  • 4. Published

  Não informar a seção caso não precise dela

• Dentro de cada seção, os atributos e métodos são classificados em ordem alfabética seguindo a ordem:

  • 1. Atributos internos: variáveis ou constantes
  • 2. Método constructor
  • 3. Método destructor
  • 4. Métodos: procedure ou function, a palavra reservada não influencia na ordem alfabética
  • 5. Eventos: métodos que começam com “On”
  • 6. Atributos publicados, property

• A Identação padrão é a mesma definida pela IDE Delphi ou Lazarus com as seguintes alterações:

  • Margem direita 90
  • Diretivas seguem identação

• As units devem ser salvas seguindo o padrão de nomenclatura do projeto: RAL + escopo da unit, por exemplo: RALClient. Dentro da pasta relativa ao escopo de projeto, como base, utils, database…

• Os escopos de projeto atuais são:

  • Base = pasta que contém as units referentes ao funcionamento mínimo do pacote e são obrigatórias na compilação para o pacote-base funcionar.
  • Utils = pasta que contém funções diversas, mapeadores e demais métodos que são utilizados por várias outras units.
  • Database = pasta que contém todas as units referentes ao tráfego de informações DBWare.

• Caso o código seja para um pacote diferente, precisa ficar contido no escopo de projeto relacionado a ele, por exemplo um motor de dados possui os arquivos de projeto .dpk dentro de \pkg\<IDE> e as units ficam em \src\engine\<motor>. Basta seguir esse modelo ou entrar em contato seja abrindo uma issue de dúvida, ou uma discussão no GitHub, ou acessando o grupo de suporte do componente.

/// Unit that represents the code that complies with documentation for contributors.
unit RALExample;

{$I PascalRAL.inc} // necessary since there's a conditional directive below

interface

uses
  {$IFDEF RALWindows} Windows, {$ENDIF}
  Classes, SysUtils;

type
  /// Example that follows the documentation as a guideline for contributors.
  TMyExample = class
  private
    FSomething: sometype;
  public
    constructor Create;
    destructor Destroy; override;
    /// Returns something
    function GetSomething: sometype;
    /// Defines something
    procedure SetSomething(AParam: sometype);
    /// Event to be called during something
    procedure OnSomething(AParam: sometype);

    property Something: sometype read GetSomething write SetSomething;
  end;

implementation
[...]

end.