Boletim Tcnico

Boas Prticas de Programao

Produto : Microsiga Protheus / Engenharia de Servios / Verso 20120829

Data da publicao : 30/08/12 Pas(es) : Brasil

Aplicabilidade Regras para um desenvolvimento de programas padronizado

A rea de Engenharia de Servios visa agrupar os programas / fontes / rotinas como componentes, artefatos cujo
objetivo a reutilizao e reduo de tempo/custos.
Portanto, padronizar as codificaes uma das primeiras preocupaes que temos.

Este boletim no foi construdo a partir do nada e nem se espera que seja um ponto final sobre o assunto.

Escolhemos um padro de documentao que se baseia no que j foi descrito / publicado / pensado pela empresa.

Na parte final constam links importantes do ByYou / TDN que enriquecem e detalham cada tpico.

Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao 1

 Boletim Tcnico

REGRAS DE BOAS PRTICAS DE PROGRAMAO

1) Utilizar o padro Protheus.Doc para documentar o fonte e as funes (Static inclusive).

O objetivo desta padronizao extrair uma documentao de forma automtica atravs de
rotina elaborada pela Fbrica de Software que gera um conjunto de pginas html a partir das
marcaes (palavras precedidas por @).

Segue um exemplo com funes fictcias:

2 Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao

 Boletim Tcnico

//----------------------------------------------------------
/*/{Protheus.doc} Proc001
Funo Proc001
@param cNome Informe o Nome
@param cTipo Informe o Tipo

@return No retorna nada

@author Alex Sandro Valario
@owner Totvs S/A
@version Protheus 10, Protheus 11
@since 22/08/2012 - data de reviso do artefato

@sample
// Proc001 - User Function pra que gera os dados
U_Proc001( cNome, cTipo )

Return

@obs Rotina ficticia

Link oficial de rotinas relacionadas: http://tdn.totvs.com.br

@project MIT044_Proc001.doc
@menu \SIGAFAT\Atualizacoes\Cadastro\Proc Geral
Parametros: Codigo De Codigo Ate - ZZZZZZZ

@history
17/08/2012 - A programao fornecida foi desvinculada do PE original
e transformada em User Function
20/08/2012 - Acrescimo de cabecalho Protheus.Doc
/*/
//----------------------------------------------------------
User Function Proc001(cNome, cTipo)
Local cTeste := GetMV("MV_ULMES")

Grava() // Rotina que prepara a massa de dados e grava as informaes

Return

//----------------------------------------------------------
/*/{Protheus.doc} Grava
Funo Grava
@param No recebe parmetros
@return No retorna nada
@author Alex Sandro Valario
@owner Totvs S/A
@obs Grava os dados
@history
20/08/2012 - Acrescimo de cabecalho Protheus.Doc
/*/
//----------------------------------------------------------
Static Function Grava()
Prepara() // Rotina que prepara a massa de dados

Atualiza() // Rotina que atualiza os dados

Return

Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao 3

 Boletim Tcnico

//----------------------------------------------------------
/*/{Protheus.doc} Prepara
Funo Prepara
@param No recebe parmetros
@return No retorna nada
@author Alex Sandro Valario
@owner Totvs S/A
@obs Prepara os Dados
@history
20/08/2012 - Acrescimo de cabecalho Protheus.Doc
/*/
//----------------------------------------------------------
Static Function Prepara()

Return

//----------------------------------------------------------
/*/{Protheus.doc} Atualiza
Funo Atualiza
@param No recebe parmetros
@return No retorna nada
@author Alex Sandro Valario
@owner Totvs S/A
@obs Prepara os Dados
@history
20/08/2012 - Acrescimo de cabecalho Protheus.Doc
/*/
//----------------------------------------------------------
Static Function Atualiza()

Return

4 Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao

 Boletim Tcnico

2) Nome de Variveis com primeira letra respeitando a Notao Hngara

3) Considere a incluso de comentrios teis pelo menos nas seguintes situaes:

3.1) Comente a chave do ndice utilizado ao lado da funo dbSetOrder/dbOrderNickName
descrevendo quais campos compem a chave
3.2) Quando utilizar strings de um arquivo CH insira um comentrio ao lado com o texto da
string
3.3) Comente eventuais clculos explicando qual lgica foi adotada
3.4) Comente trechos de cdigo explicando de forma sucinta sua finalidade
3.5) Em caso de chamada de funo do padro documentar os parmetros esperados e o
retorno (se houver)

4) Ao manipular tabelas (do padro, temporrias, retornos de queries, etc) de preferncia

especificar o Alias na frente do nome do campo

5) Priorizar declarao de Variveis inicializando-as com um valor default conforme padro

(h um link no TDN - no final do documento - descrevendo esses valores iniciais)

6) Pontos de Entrada obrigatoriamente devem fazer uso das funes GetArea() e RestArea()
devendo-se utilizar uma varivel pra cada rea utilizada alm da rea desconhecida.
Segue exemplo:

Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao 5

 Boletim Tcnico

//----------------------------------------------------------
/*/{Protheus.doc} M460FIM
Funo M460FIM
@param Nenhum parmetro
@return No retorna nada
@author Marcelo Vicente
@owner Totvs S/A
@version Protheus 10, Protheus 11
@since 22/08/2012 - data de reviso do artefato
@obs
Link oficial do Ponto de Entrada:
http://tdn.totvs.com.br/pages/viewpage.action?pageId=6784180
Ponto de Entrada no final da gerao de Nota Fiscal de sada (PE: M460Fim)
Tabelas manipuladas no PE: 3 (SF2, SD2 e SE1).
Quantidade de variveis de controle de GetArea / RestArea: 4 (quatro)

@project MIT044_GravaDadosAposGerarNotaDeSaida.doc
@menu Rotina no pode ser acessada diretamente do menu
@history
20/08/2012 - Elaborao do Ponto de Entrada
20/08/2012 - Acrescimo de cabecalho Protheus.Doc
/*/
//----------------------------------------------------------
User Function M460Fim()
// chamo de rea desconhecida
// que a rea de trabalho do desenvolvedor ao executar a User Function
Local aArea := GetArea()

Local aAreaSF2 := SF2->( GetArea() )

Local aAreaSD2 := SD2->( GetArea() )
Local aAreaSE1 := SE1->( GetArea() )

<instrues do processamento>

RestArea(aAreaSF2)
RestArea(aAreaSD2)
RestArea(aAreaSE1)

// A primeira rea guardada deve ser a ltima rea a ser restaurada

RestArea(aArea)

Return

6 Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao

 Boletim Tcnico

7) Ao gravar dados considere:

7.1) priorizar o uso de 'controle de transao' considerando o seguinte critrio: ou grava tudo
ou nada (DisarmTransaction)
7.2) nunca colocar a instruo 'EndTransaction' dentro de um bloco condicional para que no
se corra riscos da transao ficar presa
7.3) nunca incluir qualquer funo que dependa de interao com o usurio (telas, alertas -
MsgYesNo, por exemplo) aps a abertura do 'controle de transao'

8) Sobre Queries considere:

8.1) devem ser protegidas pela clusula #IFDEF TOP
8.2) devem conter a condio WHERE D_E_L_E_T_ = ' ' ao invs de WHERE D_E_L_E_T_ <> '*'
8.3) utilizar a funo RetSqlName() para compor a clusula FROM

9) Cuidados com o Operador IGUAL

O operador igual de forma simples ou dupla ( = ou == ) tem o mesmo funcionamento quando
a comparao entre dados numricos e datas.
No caso de comparao entre strings para que se tenha uma comparao exata deve-se
utilizar o operador igual no formato duplo igual ( == ).

10) Nomes de pastas, links, mapeamentos, endereos de IP interno, etc devem ser colocados
dentro de parmetros (SX6) flexibilizando a rotina/programa

11) Se for possvel, construir o cdigo dividindo-o em partes menores e agrupadas

priorizando o uso de funes curtas.

12) No uso de Interfaces visuais dar preferncia para os comandos que facilitam a leitura do
cdigo ao invs de utilizar o construtor da classe

// Verso utilizando o construtor

oSay:= TSay():New( 05, 05, {||"Texto para exibio"}, oDlg, , , , ,,.T., CLR_RED, CLR_WHITE, 200, 20)

// Verso utilizando o comando

@15,05 Say oSay Prompt "Texto para exibio" Of oDlg Pixel Colors CLR_RED, CLR_WHITE Size 200,20

Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao 7

 Boletim Tcnico

13) Prever eventuais possibilidades de "erro" causados pelo programa gerando arquivos de
Logs, ou mensagens impressas no Console (ConOut) ou ainda telas amigveis para o usurio
evitando ao mximo que a instncia seja derrubada abruptamente

14) Vetores, Arrays ou Matrizes precisam ter suas posies bem documentadas e, em caso de
estruturas grandes (maiores que 10 posies), aconselha-se a utilizao de Nomes definidos
(clusula #DEFINE) para cada coluna do array.
Segue exemplo para um vetor de 6 posies:

8 Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao

 Boletim Tcnico

#INCLUDE "protheus.ch"
#DEFINE _ARRAY_CODIGO 01 // Cdigo do Produto
#DEFINE _ARRAY_GRUPO 02 // Grupo
#DEFINE _ARRAY_DESCR 03 // Descrio do Produto
#DEFINE _ARRAY_IR 04 // IR Sim ou No
#DEFINE _ARRAY_NCM 05 // Codigo NCM
#DEFINE _ARRAY_QTDVEN 06 // Quantidade Vendida

//----------------------------------------------------------
/*/{Protheus.doc} DadosSB1
Funo DadosSB1
@param Recebe um Array com dados dos Produtos
@return Retorna o mesmo Array com as quantidades vendidas por Produto
@author Marcelo Vicente
@owner Totvs S/A
@version Protheus 10, Protheus 11
@since 22/08/2012 - data de reviso do artefato

@obs
Posio _ARRAY_CODIGO 01 -> Cdigo do Produto
Posio _ARRAY_GRUPO 02 -> Grupo
Posio _ARRAY_DESCR 03 -> Descrio do Produto
Posio _ARRAY_IR 04 -> IR Sim ou No
Posio _ARRAY_NCM 05 -> Codigo NCM
Posio _ARRAY_QTDVEN 06 -> Quantidade Vendida
Cenrio: Suponha uma funo que tenha que acumular quantidades dos pedidos num
Array / Matriz recebido por parmetro.
A Rotina varre a tabela SC6 (Itens de Pedidos de Venda) e acumula as
quantidades na posio _ARRAY_QTDVEN.

@project MIT044_DadosDosProdutos.doc
@menu Rotina no pode ser acessada diretamente do menu
@history
01/08/2012 - Criao da rotina
20/08/2012 - Acrescimo de cabecalho Protheus.Doc
/*/
//----------------------------------------------------------
Static Function DadosSB1(aSB1Dados)
Local nI := 0
Local cFilSC6 := xFilial("SC6")

DbSelectArea("SC6")
DbSetOrder(2) // C6_FILIAL+C6_PRODUTO+C6_NUM+C6_ITEM

For nI := 1 To Len(aSB1Dados)
If DbSeek( cFilSC6 + aSB1Dados[nI, _ARRAY_CODIGO] )
While SC6->( !Eof() ) .And. SC6->C6_FILIAL == cFilSC6

aSB1Dados[ nI, _ARRAY_QTDVEN ] += SC6->C6_QTDVEN

SC6->( DbSkip() )
EndDo
EndIf
Next nI

Return aSB1Dados

Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao 9

 Boletim Tcnico

15) Disponibilizar dentro do prprio programa cdigo para a criao do grupo de perguntas
(SX1) e/ou parmetros

16) Se possvel transforme o cdigo que compe um Ponto de Entrada numa funo dentro
de outro arquivo 'PRW' deixando no Ponto de Entrada apenas a chamada da funo

10 Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao

 Boletim Tcnico

LINKS / REFERNCIAS SOBRE O ASSUNTO

Seguem links e referncias que foram cruciais na elaborao do Boletim:

01) ByYou / Comunidade CD SP / Documentos / Curso de Inverno - Boas Prticas de

Programao.pptx (apresentao do Danilo Dias - danilo.dias@totvs.com.br
Link da Comunidade -> https://totvs.byyou.com/docs?space=cdsp
Link sobre Boas Prt. -> http://tdn.totvs.com/pages/viewpage.action?pageId=22480352

02) Protheus.Doc
http://tdn.totvs.com.br/pages/viewpage.action?pageId=22480577

03) Notao Hngara e declarao de variveis

http://tdn.totvs.com.br/pages/viewpage.action?pageId=22480468
http://tdn.totvs.com.br/display/tec/Posicionamento
http://tdn.totvs.com.br/pages/viewpage.action?pageId=22480476

04) Queries
http://tdn.totvs.com.br/pages/viewpage.action?pageId=27675604
http://tdn.totvs.com.br/pages/viewpage.action?pageId=27675608

05) Documentar parmetros de chamadas de funes

http://tdn.totvs.com.br/pages/viewpage.action?pageId=22480488

06) Comentrios
O que no comentar -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888922
O que comentar -> http://tdn.totvs.com.br/display/tec/O+que+comentar
Coment. Compactos -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=27675869
Coment. Precisos -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888933

07) Tcnica de elaborao de funes

http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888870
http://tdn.totvs.com.br/display/tec/Estrutura+do+programa
http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888861
http://tdn.totvs.com.br/pages/viewpage.action?pageId=23889032
http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888956

08) Variveis
Atribuio -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=23889012
Variveis pblicas -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=23889016
Uso de var. pblic -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=23889018
Valores constantes -> http://tdn.totvs.com.br/pages/viewpage.action?pageId=27675817

Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao 11

 Boletim Tcnico

09) Classe Visuais

http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888968

10) Algumas protees contra erros

http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888924

11) Perguntas (SX1) / Parmetros

http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888900
http://tdn.totvs.com.br/pages/viewpage.action?pageId=23888904

12) GetArea / RestArea

http://tdn.totvs.com.br/pages/viewpage.action?pageId=24346925
http://tdn.totvs.com.br/pages/viewpage.action?pageId=24347058

12 Engenharia de Servios Boletim Tcnico de Boas Prticas de Programao