Qualidade e documentaçãoSeçãoOpcional
Planejamento, testes, impacto das alterações, comentários úteis, cabeçalhos e nomes expressivos.
FONTE HISTóRICAPublicado
Manual de Programação Protheus (2001)
31 páginas · qualidade · variáveis · banco de dados · interfaces · customizaçãoConheça os princípios de programação e os cuidados de atualização reunidos em um manual interno da era AP5/TopConnect.
Visão geral
O Manual de Programação é um documento colaborativo da Microsiga, criado em contexto anterior ao AdvPL atual e preservado em arquivo com data de 11 de julho de 2001. Em 31 páginas, reúne orientações sobre legibilidade, documentação, variáveis, posicionamento de registros, relatórios, interfaces, pontos de entrada, dicionário SX, transações, pré-processador, queries, filial, integridade referencial e rotinas automáticas. Seus princípios gerais continuam úteis, mas nomes de produtos, ferramentas, funções e procedimentos precisam ser confirmados no TDN e na versão atual do Protheus.
Sintaxe
31 páginas · qualidade · variáveis · banco de dados · interfaces · customizaçãoParâmetros
Variáveis e estadoSeçãoOpcional
Declaração, inicialização, escopo, prefixos de tipo e preservação do ambiente com GetArea()/RestArea().
Dados e relatóriosSeçãoOpcional
DbSeek(), índices, filtros, filial, totais, consultas coerentes e prevenção de loops.
CustomizaçãoSeçãoOpcional
Pontos de entrada, arquivos SX, transações, includes, diretivas e strings traduzíveis.
Arquitetura e integraçãoSeçãoOpcional
Arquivos cliente/servidor, TopConnect, queries, integridade referencial e rotinas automáticas.
Checklist moderno derivado do manual
// Antes da alteração
// 1. Delimite a regra e os programas afetados
// 2. Confirme funções e APIs no TDN atual
// 3. Preserve áreas, ordens e filtros quando necessário
// 4. Valide buscas, retornos e condições de saída
// 5. Teste filial compartilhada e exclusiva
// 6. Registre criação, revisão, fonte e impactoResultado esperado
Os princípios históricos são convertidos em critérios verificáveis sem perpetuar ferramentas obsoletas.
Leitura segura com restauração do ambiente
User Function ExLeituraSegura()
Local aArea := GetArea()
DbSelectArea("SB1")
DbSetOrder(1)
If SB1->(DbSeek(xFilial("SB1") + "000001"))
ConOut(SB1->B1_DESC)
EndIf
RestArea(aArea)
ReturnResultado esperado
A busca é validada e o ambiente recebido pela função é restaurado antes do retorno.
- Estude a rotina e seus consumidores antes de alterar o fonte; teste também os programas afetados e use uma base diferente daquela moldada durante o desenvolvimento.
- Comentários devem explicar intenção, regra de negócio, pré-condição ou impacto. Repetir literalmente o que a instrução faz não melhora a manutenção.
- Declare e inicialize variáveis explicitamente, use nomes que revelem finalidade e prefira o menor escopo compatível com o comportamento necessário.
- Antes de gravar, valide posicionamentos e retornos. Após manipular uma área, restaure ordem, filtro, registro e ambiente quando a rotina não for proprietária desse estado.
- Laços de leitura precisam de condição de saída, avanço do cursor e limite de filial. Em arquitetura de servidor, um loop infinito pode afetar todos os usuários.
- Centralize regras usadas por relatórios e consultas diferentes para evitar totais ou critérios divergentes.
- Mudanças em dicionário, campos, índices e parâmetros devem acompanhar o mecanismo oficial de atualização e documentação da versão atual.
- AP5, TopConnect, ATUSX, Quark e SourceSafe refletem ferramentas e processos da época; não os trate como fluxo atual sem confirmação.
- Algumas assinaturas e exemplos possuem erros tipográficos ou parâmetros inconsistentes. Eles não foram promovidos a páginas técnicas sem outra fonte confiável.
- A recomendação histórica de retorno único, índices temporários e determinadas funções internas não é uma regra universal para código moderno.
- Funções contábeis, cópia cliente/servidor e rotinas automáticas variam por release e módulo; exigem documentação específica e homologação.
- O documento não informa autor individual nem número de edição. A data registrada corresponde ao arquivo fornecido.