Padrões e convenções de codificação em Centura

©PROCENGE 2005, todos os direitos reservados

Desenvolvimento Pirâmide ERP

Padrões e convenções de codificação em Centura



Introdução Padrões de codificação

Nomenclaturas Componentes visuais Convenções

Tratamento de erros

Agenda



Objetivo Apresentar os padrões básicos para o

desenvolvimento dos sistemas que utilizam o Centura como linguagem.

Documento referência (completo/detalhado) DA.07.Codificação em Centura

Padrões abordados Pir21

Módulos: Faturamento e Integração Pirâmide

Módulos: Comercial, Financeiro, Fiscal, Materiais, Orçamento, Qualidade, ...

Introdução



ArquivosIntrodução

Tipo de arquivo Função

Libraries (*.apl)

Serão denominados a partir de agora de Apls. Nelas são desenvolvidas todas as funcionalidades, telas, classes, etc. Cada Apl deve conter apenas uma funcionalidade, de forma a facilitar a manutenção.

Text (*.apt)Serão denominados a partir de agora de Apts. São os arquivos utilizados para geração de executáveis. Cada módulo do sistema tem seu respectivo Apt.



Padrões dePadrões decodificaçãocodificação



Nomenclatura de arquivosPadrões de codificação

Tipo de arquivo Nomenclatura

AplsDeve fazer referência ao nome da funcionalidade que ela possui. Exemplos:

• AjudaContexto.apl• Pedido.apl

AptsDevem fazer referência ao nome do módulo. Exemplos:

• Integração.apt• Ativo.apt



Nomenclatura de variáveisPadrões de codificação

Padrão SintaxePir21 <prefixoDoEscopo>_<prefixoDoTipo>NomeVariavel

Piramide <prefixoDoEscopo><prefixoDoTipo>NomeVariavel

Escopo Pir21

Piramide

Global do Sistema g

Global do Form w

Local (funções) l

Param. Entrada p p

Param. Saída r r

Tipo Pir21 PiramideNumber n n

Date/Time dt dt

String s s

Sql Handle hSql hSql

File Handle hFile hFile

Long String ls ls

Array a<tipoDado> a<tipoDado>

Window Handle h h

Objetos o tob

Objetos Proxy p



Nomenclatura de componentes visuaisPadrões de codificação

Componente Pir21 PiramidePushButton pb pbScrollbar Horizontal hsb hsbScrollbar Vertical vsb vsbCheckBox cb cbRadioButton rb rbDataField df dfMultilineText ml mlBackground TextGroupBox gb gbTable tbl tblColumn col colListBox lb lbComboBox cmb cmbActiveX ax ax



Nomenclatura de constantes

Nomenclatura de funções

Padrões de codificação

Tipo da Constante Pir21 PiramideMensagens PFM_NomeMsg PAM_NomeMsgNegócio BOC_NOMECONSTANTE NOMECONSTANTESistema PFC_NomeConstante NOMECONSTANTEAtributos de Classe BOA_<Função>_NomeAtributo

Erros de Sistema PFE_NomeErro Err_NomeErroErros de Negócio BOE_<Módulo>_NomeErro Err_NomeErroMensagens de Erro PFE_Msg_NomeErro

Tipo da função Pir21 PiramideInterna PFNomeDaFuncao Gx_NomeDaFunção

Externa NomeDaFunção fNomeDaFunção



Nomenclatura de classesPadrões de codificação

Tipo da Classe Pir21 PiramideConcretas CNomeClasse CNomeClasse

Interfaces INomeClasse

Proxy NomeClasse

Visuais W<TipoClasse(2letrasMinusculas)>NomeClasse

Negócio BCNomeClasse tobNomeClasse

Básicas de Negócio BCBaseNomeClasse BCBaseNomeClasse

Tipo do atributo Pir21 Piramide

Classe c_<prefixodetipo>NomeVariável

Instância m_<prefixodetipo>NomeDaVariavel

Tipo do método Pir21 PiramidePrivado __NomeDoMétodo __fNomeDoMétodoPúblicos NomeDoMétodo fNomeDoMétodoVirtuais _NomeDoMétodo _fNomeDoMétodo



Componentes visuais (1/3)Padrões de codificação

Componente Pir21 Piramide Piramide (com icone)

PushButton

pbBasicpbAlterar

pbCancelarpbDetalharpbExcluirpbGravar

pbImprimirpbIncluirpbNextpbOk

pbPreviouspbProcurar

pbSair

pbPadraopbPadraoAlterarpbPadraoCancel

arpbPadraoCopiapbPadraoDetalh

arpbPadraoEmitirpbPadraoExcluirpbPadraoGravarpbPadraoImprim

irpbPadraoIncluirpbPadraoLancar

pbPadraoOkpbPadraoSair

pbCancelarpbCliente

pbConfigurarpbConfigurarNDO

pbCopiapbDetalhar

pbEmitirpbExcluir

pbFormulapbFornecedor

pbGravarpbImprimirpbIncluir

pbOkpbPagarpbParar

pbProcurarpbReceber

pbSairpbTransfere




Componente Pir21 Piramide

Column

colCodeDesccolDate

colHelpContextcolLong

colNumbercolPrimaryKey

colStringcolValorAtributo

colChavePadraoNewcolCodeDescNew

colPadraoNew

Combo Box

cmbBasiccmbClasseMaterial

cmbCodeDesccmbDeposito

cmbDescEmpresacmbDescFilial

cmbDescriptioncmbSubclasseMaterial

cmbTipoMaterialcmbUF

cmbPadraoNewcmbClasseMaterialcmbCodeDescNew

cmbDescEmpresaNewcmbDescFilialNew

cmbDescriptionNewcmbSubclasseMaterial

cmbTipoMaterialcmbPadraoUFNew




Componente Pir21 Piramide

CheckBox cbBasic cbPadraoNewRadioButton rbBasic rbPadrao

DataFielddfDatedfLong

dfNumberdfString

dfPadraoNewdfDate2000New

MultilineTextmlDescription

mlLongmlString

mlDescriptionmlPadraoNew

BackgroundText bckBasic bckPadraoGroupBox gbBasic gbPadrao

Table tblBasic tblPadraoNew

List Box lbBasiclbCodeDesc lbPadrao



Convenções SQL Recomendações

O nome de campos e tabelas devem estar sempre em caixa alta. As palavras reservadas do SQL devem ser escritas com letra inicial maiúscula.

Utilizar os binds (:NomeVariável) nas cláusulas Where que utilizam variáveis como critério.

Exemplo:Select CLIENTE From CLIENTES Where CLIENTE = :sCodCliente




Convenções Formulários (Forms) Existem algumas operações básicas que devem

ser feitas sempre que um formulário é aberto e fechado:




Convenções Formulários (Forms) Formulários de manutenção simples

Os formulários "frmMnt" (padrão Pirâmide) e "frmBasicMnt" (padrão Pir21) devem ser utilizados para cadastros simples, que não envolvam mais de quatro atributos.

Para utilizá-los, basta criar as colunas de acordo com a funcionalidade e redefinir os métodos virtuais de seleção, inserção, update e deleção dos dados da tabela.




Convenções Formulários (Forms) Formulário de manutenção simples (padrão

Pirâmide)




Convenções Formulários (Forms) Formulário de manutenção simples (padrão

Pir21)




Convenções Formulários (Forms) Browser e formulários de manutenção

Trata-se de uma tela de navegação a partir da qual podem ser realizadas operações referentes a cadastros ou movimentações);

Se o cadastro possuir mais de quatro atributos e não for complexo, oferecendo poucas funcionalidades alem da manutenção (inclusão, alteração, exclusão e detalhamento), uma tela de browser deve ser criada;

Outras operações como cancelamentos, impressão, autorizações, entre outras, poderão ser chamadas a partir de botões do browser. (Caso o browser esteja com excesso de objetos visuais ou a operação necessite de filtros específicos, pode-se criar uma tela específica para a operação a ser realizada).




Convenções Formulários (Forms) Browser e formulário de manutenção (padrão

Pirâmide)




Convenções Formulários (Forms) Browser e formulário de manutenção (padrão

Pir21)




Convenções Classes de sistema Existe uma classe genérica previamente instanciada que pode ser

utilizada em qualquer trecho do código. Essa classe genérica agrupa diversas funcionalidades.

Convenções Empresa Existem funções pré-definidas que devem ser utilizadas para

recuperar a empresa selecionada no MDIPrincipal.


Dado Piramide Pir21Código tobPir.tGetS(“EMPRESA”) Global.GetEmpresa()

Nome tobPir.tGetS(“EMPRESA_NOME”) Global.GetEmpresaNome()

Piramide Pir21Nome da classe tobPiramide PGlobal

Nome da instância tobPir Global



Convenções Funções de conexão Principais operações a serem executadas na base dados e

as respectivas funções que devem ser usadas:


Funcionalidade Piramide Pir21

Abertura de conexão Set hSql = oConexao.fGH() Global.db.GetHandle(w_hSql)

Fechamento de conexão oConexao.fFH(hSql) Global.db.FreeHandle(w_hSql)

Abertura de transação tobPir.tBeginTransaction() Global.db.BeginTransaction()

Commit de transação tobPir.tEndTransaction() Global.db.EndTransaction()

Rollback de transação tobPir.tCancelTransaction() Global.db.CancelTransaction()

SQL Handle comum hSqlComum Global.db.GetBasicHandle()



Convenções Recuperação de parâmetros Padrão Piramide

Padrão Pir21Os parâmetros globais devem ser recuperados através da PGlobal:

Global.param.GetParam(“NOME_PARAMETRO”)Para recuperar os parâmetros por empresa, deve-se utilizar um objeto da classe

CParametroEmpresa. Uma vez o objeto declarado, deve-se fazer uma carga dos parâmetros, utilizando o serviço LoadParam do objeto.Sintaxe: oParam.LoadParam(sEmpresa, “NOMEPARAM1, NOMEPARAM2, ...”, sOrigem)onde “NOMEPARAM1, NOMEPARAM2, ...” Lista dos parâmetros que se deseja carregar o valor. Se nulo, carrega todos.sOrigem Origem à qual pertence o parâmetro. Também é opcional.

Feita a carga dos parâmetros, para recuperar seu valor deve-se utilizar o método GetParam() do objeto:Set sValorParametro = oParam.GetParam(“NOME_PARAMETRO”)


Tipo do Parâmetro Modo de Recuperação

Global fBuscaParam (“NOME_PARAM”, sValorParam)Empresa fEmpresaParam (“NOME_PARAM”, sValorParam)

Filial fEmpresaParamP (sEmpresa, “NOME_PARAM”, sValorParam)



TratamentosTratamentosde errosde erros



O tratamento de erros deve ser feito através do empilhamento da mensagem de erro no momento em que o mesmo acontece e sua posterior exibição na interface.

A exibição de mensagens de erro (ou outros tipos de mensagens) nunca deverá ser feita dentro de um objeto de negócio ou dentro de uma transação.

As mensagens de erro ficam armazenadas no banco de dados, na tabela PIR_ERROS. No padrão Pir21, a utilização da tabela PIR_ERROS é obrigatória, não sendo permitido a transcrição de mensagens de erro diretamente no código fonte.

Para empilhar o erro devem ser utilizadas constantes de erros que indicam o código do mesmo no banco de dados. As mensagens podem receber parâmetros que facilitem o entendimento ou identificação da causa do erro. Isso deve ser feito utilizando o símbolo % precedido de um índice para o parâmetro, conforme exemplo:“Não foi possível gravar o pedido ‘%1’ da filial ‘%2’.”

Os parâmetros das mensagens serão passados para funções de empilhamento de erro. Devem formar uma única String, sendo os parâmetros separados por um #. No exemplo acima, caso o erro tenha acontecido para o pedido ‘000123’ da filial ‘001’, a string de parâmetros deverá ser ‘000123#001’.

Tratamento de erros



Padrão PirâmideO empilhamento e exibição dos erros são feitos através do objeto tobPir. As

funções deverão sempre retornar TRUE ou FALSE, de forma que a interface identifique a existência ou não de erros e decida se irá exibir ou não a mensagem.

If Not fGravarPedido() If Not fGravarPedido() Return FALSE Mostra mensagem de erro.

Padrão Pir21O empilhamento e exibição dos erros são feitos através do objeto Global. As

funções deverão sempre retornar constantes de erro, ou a constante PFC_Ok, que indica que a função foi executada com sucesso. O retorno de uma função sempre deve ser testado utilizando-se a função PFFailed(nReturn) ou PFSucced(nReturn), onde nReturn é a constante de erro retornada pela função.

Set nReturn = GravarPedido() Set nReturn = GravarPedido() If PFFailed(nReturn) If PFFailed(nReturn) Return nReturn Mostra mensagem de erro.

Tratamento de erros



Formas de empilhamento e exibição das mensagens de erro

Método tError do tobPiramide

Pode ser utilizada tanto para empilharquanto para exibir erros, mas não suportaas mensagens de erro gravadas emPIR_ERROS.

Quando o erro detectado for erro de banco, oparâmetro pnError deve receber a constanteErr_SQL e o handle SQL deve ser enviado parao parâmetro phSqlErro.Ex.: Call tobPir.tError( 0, Err_SQL, '',hSqlComum)

Quando o erro detectado for erro de negócio, o parâmetro pnError deve receber a constante de erro correspondente. Estas constantes deverão estar declaradas em Constant.apl. O handle SQL a ser enviado para o parâmetro phSqlErro deve ser hWndNULL.Ex.: Call tobPir.tError(0, Err_ClienteInvalido, '', hWndNULL)

Para exibir erros empilhados: Call tobPir.tError(1,1, 'Erro ao gravar', hWndNULL)

Tratamento de erros




Método tErrorApp do tobPiramide Pode ser utilizada tanto para empilhar quanto para exibir erros,

e suporta as mensagens de erro gravadas em PIR_ERROS.

Exemplo: Call tobPir.tErrorApp(0, Err_PedidoVenda,'Erro inserindo pedido', ‘000123#001’, ‘fInserPedido’, hWndNULL)

Tratamento de erros




Método __PushPckErro do tobPiramide Deve ser utilizado para empilhar mensagens de erro retornadas

por processamento em packages. A exibição da mensagem é feita através da tobPir.tErrorApp. O parâmeto “p_nCode” é o código de erro retornado pela package e o prâmetro “p_sPackage” é o nome da package que retornou o erro.

Exemplo:tobPir.__PushPckError(nReturn ,PCK_PIR_TITULO_RECEBER’)

Tratamento de erros




Método Global.PushDBError Utilizado para empilhar erros de banco de dados, normalmente

após uma instrução SqlPrepareAndExecute().

Exemplo: Call Global.PushDBError( Global.db.GetBasicHandle())

Tratamento de erros




Método Global.PushAppError Utilizada para empilhar erros, suporta as mensagens de erro

gravadas em PIR_ERROS.

Exemplo: Call Global.PushAppError( BOE_VEN_PedidoVenda, ‘000123#001’, ‘GravaPedido()’, hWndNULL)

Tratamento de erros




Método Global.PushPckError Deve ser utilizado para empilhar mensagens de erro retornadas

por processamento em packages.

Exemplo: Call Global.PushPckError(nReturn , 'PCK_PIR_FATURAMENTO', Global.db.GetBasicHandle())

Tratamento de erros




Métodos Global.err.Show() e Global.ShowValidacao() Estes métodos devem ser utilizados para exibição de

mensagens de erro no padrão Pir21. O Global.ShowVailidacao() deve ser utilizado no SAM_Validate de objetos, pois já exibe a telapadrão para tratamento de errosde validação.

Tratamento de erros



Documents

Padrões e convenções de codificação em Centura