| ED\_: TEdit; | TS\_: TTabSheet; |
| PN\_: TPanel; | RB\_: TRadioButton; |
| GB\_: TGroupBox; | OD\_: TOpenDialog; |
| LB\_: TLabel; | SD\_: TSaveDialog; |
| MM\_: TMemo; | Q\_: TQuery, TFDQuery; |
| BT\_: TButton (Botões num geral); | DS\_: TDataSource; |
| CK\_: TCheckBox; | CDS\_: TClientDataSet; |
| CB\_: TComboBox; | DSP\_: TDataSetProvider; |
| LT\_: TListBox; | T\_: TTable; |
| RG\_: TRadioGroup; | FR\_: TFrxReport; |
| PC\_: TPageControl; | FDS\_: TFrxDBDataSet; |
| TB\_: TToolBar; | RV\_: TRvProject; |
| GD\_: TGrid; | DSC\_: TRvDataSetConnection; |
| MI\_: TMenuItem; | SH\_: TShape |
| IM\_: TImage | TM\_: TTimer |
| NB\_: TNotebook | Page: TPage |
| DBED\_: TDBEdit; | DBGD\_: TDBGrid; |
| DBCK\_: TDBCheckBox; | DBRG\_: TDRadioGroup; |
**Correto**
```PASCAL var LTeste: Integer; ```**Incorreto**
```PASCAL var LTeste : Integer; LTeste :Integer; ``` ##### **Atribuições****Correto**
```PASCAL LTeste := 15; ```**Incorreto**
```PASCAL LTeste:=15; LTeste:= 15; LTeste :=15; ``` ##### **Métodos****Correto**
```PASCAL procedure Ex(AParametro: Integer); procedure Ex(AParametro1, AParametro2: Integer); procedure Ex(AParametro: Integer; AParametro2: String); ```**Incorreto**
```PASCAL procedure Ex (AParametro1: Integer); procedure Ex( AParametro: Integer); procedure Ex(AParametro: Integer ); procedure Ex(AParametro1,AParametro2: Integer); procedure Ex(AParametro1 , AParametro2: Integer); procedure Ex(AParametro: Integer;AParametro2: String); procedure Ex(AParametro: Integer ; AParametro2: String); ``` ##### **Matrizes****Correto**
```PASCAL LTeste := LMatriz[0]; ```**Incorreto**
```PASCAL LTeste := LMatriz[ 0]; LTeste := LMatriz[0 ]; LTeste := LMatriz[ 0 ]; ``` ##### **Operadores binários****Correto**
```PASCAL LTeste := 1 + 1; ```**Incorreto**
```PASCAL LTeste := 1+1; LTeste := 1 +1; LTeste := 1+ 1; ``` ##### **Operadores unários****Correto**
```PASCAL LTeste := -1; ```**Incorreto**
```PASCAL LTeste := - 1; LTeste :=-1; ``` ##### **Subrotinas****Correto**
```PASCAL function MeuMetodo: String; procedure SubMetodo; begin //Código SubMetodo end; begin //Código MeuMetodo end; ```Incorreto
```PASCAL function MeuMetodo: String; procedure SubMetodo; begin //Código SubMetodo end; begin //Código MeuMetodo end; ``` ```PASCAL function MeuMetodo: String; procedure SubMetodo; begin //Código SubMetodo end; begin //Código MeuMetodo end; ``` ##### **Uses****Dica:** Para identificar se uma unit deve ser declarada na uses superior ou inferior, realize o seguinte teste: Copie a unit para a uses inferior e compile o programa, caso o processo de compilação não apresente erros, a unit deve permanecer na uses inferior. Caso contrário, mova a unit para a uses superior.
**No primeiro “uses“ (logo abaixo de “interface”) declarar as units no .dfm e nas assinaturas dos métodos.** ```Pascal interface uses Winapi.Windows, Winapi.Messages, System.SysUtils, System.Classes, Vcl.Graphics, Vcl.Controls, Vcl.Forms, Vcl.Dialogs; ``` No segundo “uses“ (logo abaixo de “implementation”) declarar as units usadas na implementação do código. ```Pascal implementation uses uExisteTabela, uProcuraRegistro, uGravaSistema; ``` A fim de evitar conflito em Merge devido a alterações em mesma linha, cada Unit deve ser declarada em linha diferente. Esse erro costuma acontecer principalmente quando há refatoração ou exclusão de algum componente visual.Correto
```Pascal implementation uses uExisteTabela, uProcuraRegistro, uGravaSistema; ```Incorreto
```Pascal implementation uses uExisteTabela, uProcuraRegistro, uGravaSistema; ``` ##### **Arrays** Ao indentar elementos de um array, eles devem seguir a lógica de ordenação de parênteses. Por não estarem em níveis diferentes de indentação, devem ser indentados da seguinte formaCorreto
```Pascal TClasse.Metodo( Parametro1, Parametro2, [Item1, Item2, Item3 Item4, Item5, Item6]); ```Incorreto
```Pascal TClasse.Metodo( Parametro1, Parametro2, [Item1, Item2, Item3 Item4, Item5, Item6]); ``` ``` TClasse.Metodo( Parametro1, Parametro2, [Item1, Item2, Item3 Item4, Item5, Item6]); ``` ##### **IN em tratamento de condições**Correto
```PASCAL Result := (Self in [cdfIncidenciadecisaojudicial, cdfIncidenciaDecisaoJudicial13Sal, cdfIncidenciaDecisaoJudicialAvisoPrevioIndenizado]); ```Incorreto
```PASCAL Result := Self in [cdfIncidenciadecisaojudicial, cdfIncidenciaDecisaoJudicial13Sal, cdfIncidenciaDecisaoJudicialAvisoPrevioIndenizado]; ``` ```PASCAL Result := (Self in [cdfIncidenciadecisaojudicial, cdfIncidenciaDecisaoJudicial13Sal, cdfIncidenciaDecisaoJudicialAvisoPrevioIndenizado]); ``` # Palavras reservadas As palavras reservadas da linguagem Delphi devem ser escritas com todas as letras minúsculas, a única exceção é a palavra String, pois segue o padrão dos tipos, os quais iniciam com letra maiúscula. As palavras reservadas do Delphi são:| absolute | forward | public |
| abstract | function | published |
| and | goto | raise |
| array | if | read |
| as | implementation | readonly |
| asm | in | record |
| assembler | index | register |
| automated | inherited | reintroduce |
| begin | initialization | repeat |
| case | inline | resourcestring |
| cdecl | interface | safecall |
| class | is | set |
| const | label | shl |
| constructor | library | shr |
| contains | message | stdcall |
| default | mod | stored |
| destructor | name | string |
| dispid | near | then |
| dispinterface | nil | threadvar |
| div | not | to |
| do | object | try |
| downto | of | type |
| dynamic | operator | unit |
| else | or | until |
| end | out | uses |
| except | overload | var |
| export | override | virtual |
| exports | package | while |
| external | pascal | write |
| far | private | writeonly |
| file | procedure | xor |
| finally | program | |
| for | property |
**Atenção:** Cada módulo possui um número de versão diferente. Caso tenha dúvidas, consulte o guia de [como identificar o número da versão de cada módulo](https://wiki.supersoft.com.br/books/padroes-de-codigo/page/como-identificar-o-numero-da-versao-de-um-modulo).
# Alteração de Registros em Massa na Atualização Sempre que houver a necessidade de realizar alterações em massa nos registros de uma tabela durante o processo de atualização do sistema, utilizamos as rotinas de atualização controladas por versão. Cada módulo do sistema possui uma unit específica para essa finalidade, nomeada como `uAtualizaCampoNulo__.pas` (onde o sufixo corresponde à sigla do módulo, ex: `uAtualizaCampoNuloCC.pas`). --- ## Estrutura de Versionamento As atualizações são encapsuladas dentro de condicionais que validam a versão atual do banco de dados (`AVersaoDasTabelas`). Isso garante que a rotina seja executada **apenas uma vez**, exatamente no momento em que o cliente atinge a versão estipulada. ##### Exemplo de Estrutura: ```pascal if (AVersaoDasTabelas < 5.185) then begin // Executa o método padrão de atualização de campos TAtualizaCampoNulo.Atualizar('PARAMCC', 'BloqueiaNumOC', 'S', 'N'); // Executa uma procedure customizada para ajustes complexos CorrigirCodClasse(); end; ``` Neste exemplo, ao atualizar o sistema para a versão **5.185**: - O método `TAtualizaCampoNulo.Atualizar` será disparado para alterar os registros do campo `BloqueiaNumOC` na tabela `PARAMCC`, substituindo os valores `'S'` por `'N'`. - A procedure customizada `CorrigirCodClasse()` será chamada para executar comandos SQL adicionais.[Como Identificar o Número da Versão de um Módulo](https://wiki.supersoft.com.br/books/padroes-de-codigo/page/como-identificar-o-numero-da-versao-de-um-modulo "Como Identificar o Número da Versão de um Módulo")
--- ## Implementação de Procedures Customizadas Para cenários onde o método `TAtualizaCampoNulo.Atualizar` não é suficiente (como atualizações que exigem regras de negócio mais complexas ou manipulação de strings), deve-se criar uma procedure interna isolada utilizando `TFDQuery`. ##### Exemplo de Procedure Customizada: ```pascal procedure CorrigirCodClasse(); var LQAux: TFDQuery; begin LQAux := CriarFDQuery(nil); try LQAux.SQL.Clear(); LQAux.SQL.Add('UPDATE NFReceb'); LQAux.SQL.Add(' SET CodClasse = LPAD(CodClasse, 2, "0")'); LQAux.SQL.Add(' WHERE CodClasse <> ""'); LQAux.ExecutarSQL(); finally FreeAndNil(LQAux); end; end; ``` # Como Identificar o Número da Versão de um Módulo ## 1. Identificar o Número do Caso via GitHub Desktop O primeiro passo é identificar a branch da versão que está sendo trabalhada. Caso não saiba qual é, verifique as informações no grupo de desenvolvimento do **Rocket.Chat**. Ao identificar o número da branch, faça a busca no **GitHub Desktop** para localizar o número do caso associado à versão. - **Exemplo de Branch:** `173-Caso-0054066` - **O que extrair:** O número após a palavra "Caso" (`0054066`) é o identificador que usaremos para consultar as versões. --- ## 2. Consultar as Relações no Mantis Com o número do caso em mãos, siga o procedimento abaixo: 1. Acesse o **Mantis** e busque pelo número do caso localizado na branch (ex: `0054066`). 2. Navegue até o tópico de **Relações** do chamado. 3. Nesta seção, estarão relacionados todos os sistemas e casos que compõem essa entrega, detalhando a versão exata de cada um. ##### Exemplo de Vínculo Encontrado: > **SSCompras Versão 5.195 - COMPRAS** Desse modo, quando houver a necessidade de aplicar scripts de estrutura de tabelas ou manutenção de registros em massa, o número `5.195` será o valor utilizado exclusivamente para o módulo de **Compras (CC)**. ---**Atenção / Vale Ressaltar:** Cada módulo possui um número de versão diferente! Nunca assumam que a versão de um sistema se aplica ao outro. A branch `173` pode atualizar Compras para `5.195`, mas conter o módulo de Estoque (CE) na versão `5.170`. Sempre confira a lista de relações para cada sigla envolvida na sua alteração.
# SQL Neste capítulo se encontram os padrões de código adotados para SQL e alguns exemplos ilustrativos, caso mesmo com os exemplos descritos, ainda restem dúvidas, não hesite em perguntar # Considerações Iniciais ### **Introdução** Para rotinas em SQL, deve-se observar as seguintes considerações: 1. **Palavras reservadas** devem ser escritas **integralmente em letras maiúsculas**. 2. Nomes de **tabelas e campos** devem utilizar a notação **PascalCase**, mantendo **siglas em letras maiúsculas**. 3. Os **aliases de tabelas** devem ser escritos **integralmente em letras maiúsculas** e utilizar abreviações **curtas e significativas** da tabela de origem. 4. **Parâmetros** devem possuir o **prefixo "P"** e utilizar a notação **PascalCase**. 5. Para facilitar a implementação e a leitura das cláusulas, as **palavras reservadas devem ser alinhadas de forma que exista uma coluna contínua separando-as dos campos e tabelas**, conforme o exemplo abaixo: ```SQL SELECT SUM(NF.ValorNF) AS ValorNF, CTE.CodigoCTE FROM NotaFiscal AS NF INNER JOIN ConhecimentoCTE AS CTE ON CTE.CodigoNF = NF.CodigoNF WHERE NF.EmpresaID = :PNotaFiscalEmpresaID AND CTE.EmpresaID = :PConhecimentoCTEEmpresaID GROUP BY CTE.CodigoCTE UNION ALL SELECT (SELECT CodigoXML FROM ArquivoXML) AS CodigoXML, RELCTE.CodigoCTE FROM DocumentoXML AS DOCXML INNER JOIN (SELECT CodigoCTE FROM RelacaoCTE) AS RELCTE ON RELCTE.CodigoCTE = DOCXML.CodigoCTE WHERE DOCXML.EmpresaID = :PDocumentoXMLEmpresaID ORDER BY 1 ``` Perceba que, na cláusula do exemplo acima, as linhas 4 e 14 possuem as **maiores palavras reservadas/expressões**. Dessa forma, **as demais palavras reservadas recebem a adição de espaços em branco à esquerda**, para que **todas as expressões terminem na mesma coluna**. Assim, forma-se uma **coluna contínua ao longo de toda a cláusula**, separando as palavras reservadas à esquerda dos campos e tabelas à direita. # Exemplo: CASE ### **Sem expressão no CASE** ```SQL SELECT T1.Campo1, T1.Campo2 FROM Tabela1 T1 WHERE T1.Campo2 = :PInformacao1 AND T1.Campo3 = :PInformacao2 AND CASE WHEN T1.Campo4 IS NOT NULL THEN T1.Campo4 = :PInformacao3 ELSE T1.Campo5 = :PInformacao3 END ``` ### **Com expressão no CASE** ```SQL SELECT T1.Campo1, T1.Campo2 FROM Tabela1 T1 WHERE T1.Campo2 = :PInformacao1 AND T1.Campo3 = :PInformacao2 AND CASE COALESCE(T1.Campo4, "") WHEN "" THEN T1.Campo5 || SUBSTRING(T1.Campo6 FROM 1 FOR 1) || SUBSTRING(T1.Campo6 FROM 3 FOR 5) ELSE T1.Campo7 END ApelidoDoCampo ``` ### **Com CASE no SELECT** ```SQL SELECT CASE WHEN EXISTS (SELECT 1 FROM Tabela1 WHERE Campo1 = :PCampo1 AND Campo2 = :PCampo2) AND EXISTS (SELECT 1 FROM Tabela1 WHERE Campo1 = :PCampo1 AND Campo2 = :PCampo2) THEN "True" ELSE "False" END AS Resultado FROM RDB$DATABASE; ``` # Exemplo: DELETE ```SQL DELETE FROM TabelaExemplo WHERE Abrev = :PAbrev AND Tipo = :PTipo AND Categoria = :PCategoria ```As comparações realizadas nas linhas 3-5 poderiam ter seus operadores alinhados na mesma coluna, entretanto essa não é uma prática recomendada para cláusulas mais extensas.
# Exemplo: Modificador DISTINCT ```SQL SELECT DISTINCT T.Campo1, T.Campo2, T.Campo3 T.Campo4, T.Campo5, T.Campo6 FROM Tabela T INNER JOIN OutraTabela O ON O.Campo1 = T.Campo7 WHERE T.Campo1 = :Param1 AND T.Campo8 = :Param2 ``` # Exemplo: UPDATE ```SQL UPDATE TabelaExemplo SET Numero = :PNumero, Nome = :PNome WHERE Categoria = :PCategoria AND Tipo = :PTipo ```As comparações realizadas nas linhas 2-5 poderiam ter seus operadores alinhados na mesma coluna, entretanto essa não é uma prática recomendada para cláusulas mais extensas
# Palavras Reservadas As palavras reservadas em SQL devem ser escritas com todas as letras maiúsculas:| ACTIVE | DOUBLE | NUMERIC |
| ADD | DROP | OF |
| AND | EDIT | ON |
| ALL | ELSE | ONLY |
| ALTER | END | OPEN |
| ANY | EXECUTE | OR |
| AS | EXISTS | ORDER |
| ASC | FILTER | OUTER |
| ASCENDING | FIRST | PERCENT |
| AT | FLOAT | PLAN |
| AVG | FOR | POSITION |
| BEFORE | FOREIGN | PRECISION |
| BEGIN | FROM | PREPARE |
| BETWEEN | FULL | PRIMARY |
| BLOB | FUNCTION | PROCEDURE |
| BY | GENERATOR | PUBLIC |
| CASE | GEN\_ID | REAL |
| CAST | GROUP | RIGHT |
| CHAR | HAVING | ROWS |
| COALESCE | HOUR | SELECT |
| COLLATE | IF | SET |
| COLUMN | IN | SIZE |
| COMMIT | INACTIVE | SOME |
| CONTINUE | INDEX | SQL |
| COUNT | INNER | SUM |
| CREATE | INSERT | TABLE |
| CURRENT | INTEGER | THEN |
| CURRENT\_DATE | INTO | TRIGGER |
| CURRENT\_ROLE | IS | TRUNCATE |
| CURRENT\_TIME | JOIN | TYPE |
| CURRENT\_TIMESTAMP | KEY | UNION |
| CURRENT\_TRANSACTION | LAST | UPDATE |
| CURRENT\_USER | LEFT | UPDATING |
| CURSOR | LENGTH | USE |
| DATABASE | LIKE | USER |
| DATE | LONG | USING |
| DAY | MAX | VALUE |
| DEC | MERGE | VALUES |
| DECIMAL | MIN | VIEW |
| DECLARE | MINUTE | WHEN |
| DEFAULT | MONTH | WHERE |
| DELETE | NAMES | WHILE |
| DESC | NO | WITH |
| DESCENDING | NOT | YEAR |
| DISTINCT | NULL | YEARDAY |
| DO | NULLIF |
Deve-se evitar ao máximo realizar commits sem mensagem, principalmente em versões e no trunk.
#### **Exemplos** --- ##### **Modelo de Mensagem**| Caso XXXXX: Descrição do caso de acordo com o Mantis/Trello. \- Mensagem descritiva e em poucas palavras do que foi alterado (Opcional) Desenvolvedor |
Ao criar um branch, deve-se informar o número do caso e a sua descrição de acordo com o Mantis/Trello.
| Caso XXXXX: Descrição do caso de acordo com o Mantis/Trello. \- Criação do branch (Opcional) Desenvolvedor |
Ao realizar o commit de alterações, além do cabeçalho indicando o número do caso e a descrição, deve-se adicionar por tópico as alterações feitas naquele commit.
| Caso XXXXX: Descrição do caso de acordo com o Mantis/Trello. \- Alterações na lógica da rotina CalcularSaldo. \- Correções no padrão de código aplicado. \- Criação da classe TGerador (Opcional) Desenvolvedor |
Ao realizar a atualização de um branch(Merge com Trunk) , deve-se adicionar a "tag" \[Atualização do Branch\] no início do cabeçalho, para que ao consultar o log de alterações, o desenvolvedor identifique prontamente quais revisões são referentes à atualizações do branch e quais não são.
| \[Atualização do Branch\] Caso XXXXX: Descrição do caso de acordo com o Mantis/Trello. (Opcional) Desenvolvedor |
Comentários que complementam o entendimento de uma rotina, mas que não tentam explicar o que está sendo feito no trecho.
--- #### **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 * ****************************************************************} ```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.
--- ##### **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. ```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.
--- ##### **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; ```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.
# Código Limpo #### **Definição de Clean Code** A apresentação de um código claro e organizado não consiste apenas na convenção nomes, constantes, classes, variáveis, espaçamento etc.. Um código limpo (*clean code*) deve ser: - Simples: fácil entendimento; - Eficiente: realizar tudo o que foi proposto; - Único: não realizar algo que outro trecho de código já faz; - Direto: não dar voltas para chegar no resultado; - Feito com atenção: o código deve ser sempre feito com preocupação e revisto depois de pronto; #### ***Bad Smells*** Em contra partida, também existem as *Bad Smells*, que como sua tradução já sugere, é algo com cheiro ruim, e representa o código com práticas que não devem ser utilizadas. Essas práticas se devem aos códigos que fogem das características de um código limpo. Abaixo são demonstrados alguns exemplos de *bad smells*. ##### **Encadeamento de If's** ```PASCAL if (Q_Manut.FieldByName('DiasDireito').AsFloat = 0) then begin if (AnsiSameText(Trim(Q_Manut.FieldByName('DiasDireito').AsString), ''))) then begin if (MessageDialog.Show('Não foi informado os dias de Direito. Deseja' + 'Continuar?', mtConfirmation, [mbYes, mbNo], 0) = mrNo) then begin Q_Manut.FieldByName('DiasDireito').FocusControl; Abort; end; end; end; ```Esse tipo de encadeamento pode ser facilmente substituído pela palavra reservada "and".
```PASCAL if (Q_Manut.FieldByName('DiasDireito').AsFloat = 0) and (AnsiSameText(Trim(Q_Manut.FieldByName('DiasDireito').AsString), ''))) and (MessageDialog.Show('Não foi informado os dias de Direito. Deseja' + 'Continuar?', mtConfirmation, [mbYes, mbNo], 0) = mrNo) then begin Q_Manut.FieldByName('DiasDireito').FocusControl; Abort; end; ``` --- ##### **Excesso de if-else** ```PASCAL if (Q_Manut.FieldByName('DiasDireito').AsFloat = 0) then LTipo := 1 else if (Q_Manut.FieldByName('DiasDireito').AsFloat = 1) then LTipo := 2 else if (Q_Manut.FieldByName('DiasDireito').AsFloat = 2) then LTipo := 3 else if (Q_Manut.FieldByName('DiasDireito').AsFloat = 3) then LTipo := 5 else LTipo := 9; ```O trecho acima pode ter sua estrutura facilitada com a utilização de um "case".
```PASCAL case Q_Manut.FieldByName('DiasDireito').AsFloat of 0: LTipo := 1; 1: LTipo := 2; 2: LTipo := 3; 3: LTipo := 5; else LTipo := 9; end; ``` --- ##### **Atribuição Indireta**Situações com atribuições indiretas aparecem constantemente no código
```PASCAL if (Q_Manut.FieldByName('DiasDireito').AsFloat = 0) then LDeveIncrementar := False else LDeveIncrementar := True; ``` ```PASCAL if (RG_TipoCliente.ItemIndex = 0) then LTipo := 0 else (RG_TipoCliente.ItemIndex = 1) then LTipo := 1; ```Basta uma pequena análise por parte do desenvolvedor para perceber que podem ser simplificadas
```PASCAL LDeveIncrementar := (Q_Manut.FieldByName('DiasDireito').AsFloat <> 0); ``` ```PASCAL LTipo := RG_TipoCliente.ItemIndex; ```