Documentador de programas 4gl

Introdução

Durante o ciclo de vida de um projecto, a documentação directamente associada à estrutura e funcionalidade do código fica rápidamente unsynchroni.

Esta facto ocorre devido à forma onde esta é normalmente armazenada.

É usual o responsável pelo desenho construir um documento onde chega por vezes ao detalhe de definir as funções, seus valores de retorno e parametros.

É tambem comum usar ferramentas CASE como o Power Designer embebendo dentro das descrições dos processos a documentação do programa a ser construido.

Na fase inicial de desenvolvimento do projecto se o gestor fôr cuidadoso, é provável que a documentação reflicta o código programado.

Quando se muda para uma fase do processo mais avançada, normalmente imediatamente a primeira entrada em exploração inicia-se o caos. O programador tem de decidir e o chefe não tem tempo para controlar tudo. Assim altera-se o código fonte, mas como o programador por definição não gosta de alterar documentos esta fica imediatamente desactualizada.

Quanto mais tempo passa mais desactualizada ela fica. Até que não serve para nada.

Seria fácil culpar os programadores, no entanto a documentação normalmente está escondida debaixo de algum servidor, num directório obscuro dentro de um documento (normalmente em formato .doc) normalmente com dezenas de páginas. A mudança de contexto é tal que de facto não me parece fácil de lhe exigir semelhante esforço.

As abordagens iniciadas com alguns trabalhos, como por exemplo literate programming são neste mercado cada vez mais utilizadas.

O Java é paradigmático: A documentação de referência de todas as API(s) é obtida por processos automáticos sobre informação contida nos sources.

Desta forma, fácilmente se defende a existência de claras melhorias, como por exemplo:
  • Ferramenta única para programação e documentação de referência (editor de texto usado na programação).
  • Fácil visualização de erros de documentação
  • Maior produtividade
  • Mais comunicação dentro da equipa de programação (dado que todas as funções estarão documentadas, estando esta fácilmente disponivel).

Este projecto dá ao 4gl aquilo que já existe no java (com o javadoc) ou no C/C++ (com projectos como o doxygen), ou seja:
  • A possibilidade de a documentação de referência estar incluida nos programas fonte
  • Geração de documentos de referência em formato fácilmente legivel e acessivel
  • Possibilidade de pesquisa
  • Documentos de referência com organizações diversas
Como é óbvio, no entanto os programadores e chefes de projecto têm de criar uma disciplina que permita que durante as alterações aos programas, os documentos tambem o sejam. Inclusivamente deve-se definir alguns padrões relativos aos comentários a inserir.

Para o impaciente

Para não obrigar à leitura completa do manual apresentam-se aqui algumas sequências tipicas para instalação e execução da ferramenta.

Compilação

As componentes que necessitam de compilação são: parser (p4gl) e classes adicionais do navegador.

Para compilar executar make no directório base da aplicação.

Instalação

Executar make install.

Execução

Apresenta-se apenas exemplos tipicos de execução com User Interface não gráfico.

Importar informação de sources

$ fgldoc --ui=CUI --action=ImportFgl --import_directory=/tmp --load_recursive

Importar informação de CSV(s)

$ fgldoc --ui=CUI --action=importCSV --sheet_file=/tmp/comments.csv --load_recursive --normalize

Exportar para sources 4gl

$ fgldoc --ui=CUI --action=export2Fgl --sheet_file=<fileName> --export_directory=<directoryName>

Exportar para CSV

$ fgldoc --ui=CUI --action=export2Csv --export_directory=<directoryName> --export_source=<fglSourceName.4gl>

Exportar para Html

$ fgldoc --ui=CUI --action=export2Html --export_html_directory=<directory_name>

Componentes

fgldoc - Interface para execução de acções de documentação

Componente que serve de envolovente à execução da(s) acções permitidas pelo documentador de 4gl. A maioria das acções de documentação são executadas por intermédio deste programa.

Está construido em perl e aceita as seguintes opções de execução:

  • --help : Define as opções permitidas
  • --ui={GUI | CUI} : User interface com o qual será executada a aplicação que poderá ser:
    • GUI : Graphical User Interface (Modo Perl / Tk)
    • CUI : Command line User Interface. Não tem interacção com utilizador. Obriga a acções minimas de execução.
  • --action=<ActionName> : Acção a executar, que poderão ser:
    • importCSV : Importa os comentários de um ficheiro com um separador fixo
    • importFgl : Importa os comentários dos source 4gl
    • export2Fgl : Exporta os comentários para os sources 4gl. Obriga os parâmetros --exportDirectory e --exportSource .
    • export2Csv : Exporta os comentários para um ficheiro com separador fixo
    • export2Html : Exporta os comentários para um conjunto de ficheiros em html devidamente interligados
  • --export_directory=<dirName> : No caso de exportação dos comentários para os sources de 4gl deve conter o nome do directório onde este(s) se encontram.
  • --exportSource=<fglname> : No caso de exportação dos comentários para os sources de 4gl irá conter o nome do programa fonte.
  • --quiet : Retira toda e qualquer mensagem enviada para o standard output.
  • --insertEmptyComment : Se afectada indica que deve ser inserido um comentário vazio numa função que não o tenha definido no repositório. Usado na opção de exportação para sources 4gl.
  • --sheet_file=<CSVfileName> : Indica o nome do ficheiro com separador CSV a usar no caso da importação e exportação para ficheiros com caracter separador.
  • --normalize : Indica que a informação carregada do ficheiro com separador CSV deve ser normalizada e não apenas mantida na tabela com estrutura exactamente igual ao ficheiro.
  • --clean_repository : Se afectado indica que o repositório deve ser limpo antes de carregada a informação.
  • --send_line_to_log
  • --package_name=s : Indica o nome do package a inserir durante o carregamente dos sources 4gl
  • --load_recursive : No caso do carregamento de informação de 4gl(s) indica que deve ser carregados os ficheiros do directório definido e de todos os sub-directórios correspondentes
  • --import_directory=s : Define o directórtio onde estão os 4gl(s) de onde se pretende carregar a informação.
  • --export_html_directory=<htmlDirectoryName> : Indica qual o directório para onde a informação em formato html será exportada / gerada
  • --ignore_exist_dir : Se afectado indica que o programa deve ignorar se o directório já existe. Utilizado pela exportação para html

Interface CUI 

CUI é uma sigla que significa Command line User Interface.

Tem como objectivo possibilitar a execução batch das operações permitidas.

É acedido quando o programa executado com  opção --ui=CUI.

Uma vez que após a sua execução não deverá existir qualquer interacção com os utilizadores , todas as opções necessárias devem ser fornecidas por linha de comando ou estar disponiveis no ficheiro de parametros (normalmente .fgldocrc).

Interface GUI  

Está construido usando o package Tk do perl. Como tal este tem de estar instalado na máquina onde se está a executar.

Um erro comum é a tentativa de execução em modo GUI numa janela de telnet sem DISPLAY de X associado, o que óbviamente não é possivel uma vez que não existe ambiente gráfico a ele associado.

Nos pontos que se seguem define-se quais as opções interactivas permitidas.

Ficheiro -> Open

Abre e lê o ficheiro que contem a configuração e opções de execução das tarefas.

Por omissão, é carregada a informação contida  no ficheiro ~/.fgldocrc.

Ficheiro -> Save

Grava as opções de execução correntes no ficheiro de parametros (normalmente ~/.fgldocrc).

Ficheiro -> Sair

Sai do programa. Antes de terminar a execução grava as opções no ficheiro de parâmetros.

Importar -> CSV

Importa comentários de um ficheiro CSV (Character Separated) para o repositório em modelo relacional (base de dados).

A importação é efectuada em duas fases:
  • Load do ficheiro para uma tabela exactamente com a mesma estrutura.
  • Normalização da informação para a 3ª forma normal, para o modelo relacional definido.

Permite parametrizar:
  • Ficheiro a importar:  Nome completo do ficheiro a carregar dando acesso a um File Chooser para a escolha. Por default a sua extensão será .txt.
  • Limpeza do repositório : Não utilizado
  • Normalização : Quando desactivado a 2ª fase não é executada.
  • Enviar linha para log : Quando activado, cada linha carregada é enviada para o log.

Se o utilizador carregar no botão <Cancel> ou fechar a janela, a operação não é executada voltando ao menu principal.


O ficheiro deve ser com separador <TAB> entre colunas e <Enter> entre linhas.

Deve conter 7 colunas cuja informação deve ser (por ordem):

  • moduleName : Nome do módulo 4gl
  • idProcess : Código do processo
  • functionName : Nome da função
  • parametro : Parâmetro
  • retorno : Descrição do retorno
  • call  :
  • comments : Comentáriodescritivo da função

Importar -> Sources 4gl

Importa a informação e comentários disponiveis nos source 4gl.

A informação que se parametriza na janela é:
  • Nome do package : Nome de package a que os módulos 4gl ficarão associados. Para já não é muito usado.
  • Localização do directório : Nome completo do directório abaixo do qual estão os sources 4gl de que se pretende efcetuar o parsing.
  • Lista de módulos : Lista completa dos módulos de 4gl de que se pretende efcetuar o parsing
  • Load comments : Indica se se pretende ou não carregar no repositório os comentários fgldoc.
  • Parse Only : Serve apenas para testar se o parsing é ou não efectuado com sucesso não carregando qualquer informação na base de dados.
  • Repositório : Informação necessária para estabelecer a conexão com a base de dados.
  • Carregamento de utilização de tabelas: Se activado qualquer informação sobre utilização de tabelas é carregada no repositório.
  • Carregar parametros : Se activado indica que o parser deve carregar os parâmetros das funções no repositório.
  • Carregar Strings : Se activado as strings serão carregadas no repositório. Ainda não está em funcionamento.
  • Carregar variáveis locais : Se activado indica que as variáveis locais serão carregadas  no repositório.
  • Recursivo : Se activado serão adicionados à lista todos os ficheiros com extensão .4gl existentes abaixo do directório definido e(ou) nos sub-directórios.

Se o utilizador carregar no botão <Cancel> ou fechar a janela, a operação não é executada voltando ao menu principal.

Exportar -> CSV

Exporta a informação disponivel no repositório relacional para um ficheiro de texto com separador fixo.

Para o conseguir desnormaliza a informação para uma única tabela (p4gl_excel) antes de gravar o ficheiro.

O interface nesta versão disponivel apresenta apenas um file chooser para que o utilizador escolha o ficheiro e localização que deseja gerar.

Se o utilizador carregar no botão <Cancel> ou fechar a janela, a operação não é executada voltando ao menu principal.

Exportar -> Sources 4gl

Insere os comentários (disponiveis no repositório) no(s) source(s) 4gl.

O comentário do módulo é inserido no inicio.

O comentário de cada função inserido imediatamente antes da sua implementação.

Permite configurar as seguintes opções:
  • Directório : Localização (nome do directório completo) onde se encontra o módulo 4gl onde se deseja inserir os comentários
  • Módulo de 4gl  : Apresenta sob a forma de lista os sources 4gl do directório escolhido. Só permite escolher um ficheiro, nesta versão.
  • Substituição de fgldocs : Se activado substitui eventuais fgldoc que existam no ficheiro, caso contrário deixa-os e cria um novo.

Se o utilizador carregar no botão <Cancel> ou fechar a janela, a operação não é executada voltando ao menu principal.

Exportar -> HTML

Embora exista um interface em JSP para navegar na documentação de 4gl directamente, por vezes é importante poder aceder à informação directamente numa àrvore de html puro (para não ficar dependente de uma infraestrutura complexa com SGBD e servidor de JSP tomcat).

Esta opção permite, por isso gerar uma estrutura de documentos html devidamente interligados e que permitem navegar na documentação exportada.

Desta forma é possivel, por exemplo disponibilizar a informação para um CD-Rom ou arquivá-la num .tgz para envio sendo fácil ao destinatário desarquivá-la e navegar.

Exporta apenas o repositório na totalidade.

Se o utilizador carregar no botão <Cancel> ou fechar a janela, a operação não é executada voltando ao menu principal.

Opções -> Mostrar log

Define se a janela de log deve ou não estar disponivel durante a execução do programa.

Opções -> Configure

Permite configurar as opções de execução das diversas acções, nomeadamente:
  • 4gl doc repository : Informação necessária para estabelecimento da conexão à base de dados
  • syspgm repository : Não usado, de momento
  • CSV import file : Nome do ficheiro usado por default para carregar o repositório com base no repositório CSV
  • XML file : Não usado, de momento .
  • CSV Export file : Nome do ficheiro onde a acção de exportação irá gravar a informação, por default.
  • XML export file : Não usado, de momento

Navegador

Construido em JSP, permite, a partir de um browser de html aceder à informação disponivel no repositório.

Divide-se genéricamente em três janelas (frames):
  • Processos de negócio 
  • Módulos / sources de 4gl (constrangidos ou não por um processo)
  • Comentários (constrangidos ou pelo módulo ou processo).
A frame de processos de negócio apresenta a lista de processos registados numa tabela e à qual estão associdas funções de 4gl. Cada um destes processos é um link que actualiza a janela que contem a lista de módulos. Existe a opção de seleccionar todos os processos.

Com base no processo seleccionado (ou todos se assim escolhido) é apresentada uma lista de módulos que conteem funções que foram associadas a um processo (com a tag @process). Cada módulo é um link que actualiza a frame de documentação de um módulo. Contem uma opção para mostrar todas as funções, de acordo com o processo préviamente seleccionmado.

Os comentários de um módulo (ou de todos consoante o escolhido) apresenta uma lista resumida das funções de um módulo, seguido depois pela informação detalhada existente no repositório, nomeadamente:
  • Nome
  • Comentário textual.
  • Parametros: Lista e descrição.
  • Retorno(s) : Descrição de cada um deles.

Ficheiro com dados de configuração

Este regista as acções que se pretende executar e respectivas opções ou informação necessária.

Este ficheiro pode ser construido manualmente ou ser gravado através de opções disponiveis no fgldoc quando este é executado (tanto em ambiente GUI como CUI).

Por omissão, o seu nome é .fgldocrc e será guardado no directório inicial do utilizador.

Nesta versão corresponde a um ficheiro que contem as afectações de variáveis (uma espécie de serialização de um objecto).


Os dados afectados são:
  • csvImportFile : Nome do ficheiro CSV de onde os dados serão importtados.
  • xmlImportFile : Não utilizado.
  • UI : Tipo de user interface utilizado.
  • action : Acção aexecutar.
  • importInformixDir : Informixdir do repositório residente em SGBD Informix.
  • importInformixServer : Informixserver dso repositório.
  • importHost : Host onde o repositório reside.
  • importDatabase : Database onde o repositório reside.
  • importUser : Utilizador para acesso á base de dados.
  • exportInformixDir : ???
  • exportInformixServer : ???
  • exportHost : ???
  • exportDatabase : ???
  • exportUser : ???
  • csvExportFile : Nome do ficheiro CSV para onde a informação será exportada.
  • xmlExportFile : Não usado
  • clearRepositoryOnImportCSV : Indica se o repositório deve ser limpo quando se importar de CSV.
  • normalize : Indica que ao importar de CSV a tabela p4gl_excel deve ser normalizada para as tabelas respectivas.
  • clearRepositoryOnImportXML : Não utilizado.
  • loadComments : ???
  • parseOnly : Indica que durante a acção de importação de sources 4gl deve ser efectuada apenas um parse do ficheiro. Usado sobretudo para validar eventuais erros de sintaxe e (ou) utilização de palavras reservadas como identificadores.
  • loadTableUsage : Indica que se pretende efectuar o carregamento de utiulização de tabelas (em SQL embebido não dinâmico).
  • loadParameters : Indica que se pretende carregar os parametros durante a acção de carregamento dos sources 4gl.
  • loadStrings : Não utilizado.
  • loadLocalVariables : Não utilizado.
  • sourceDir : Define o directório onde os ficheiros de 4gl irão estar localizados.
  • replaceFgldoc : Indica que na acção de exportação dos comentários para 4gl, estes devem ser substituidos.
  • fglSource : Indica qual o módulo de 4gl para onde os comentários devem ser exportados, na acção de exportação para 4gl.
  • logShowed : Não utilizado.
  • importFglLocation : Indica o directório onde os 4gl(s) a importar deverão estar localizados.
  • loadFilesRecursive  : Indica que o load de informação de 4gl deve ser efectuada recursivamente.

Apresenta-se, de seguida um exemplo de preenchimento automático do ficheiro de configuração.
$csvImportFile = '/usr/home/sergio/MOB.txt';
$xmlImportFile = '4gl_mapping.xml';
$UI = 'GUI';
$action = 'export2Fgl';
$importInformixDir = '/usr/informix';
$importInformixServer = 'unstable';
$importHost = 'debian';
$importDatabase = 'p4gl_repository';
$importUser = 'sergio';
$exportInformixDir = undef;
$exportInformixServer = undef;
$exportHost = 'debian';
$exportDatabase = 'p4gl_repository';
$exportUser = 'sergio';
$csvExportFile = '4gl_mapping.txt';
$xmlExportFile = '4gl_mapping.xml';
$clearRepositoryOnImportCSV = undef;
$normalize = '1';
$clearRepositoryOnImportXML = 'false';
$loadComments = undef;
$parseOnly = 0;
$loadTableUsage = undef;
$loadParameters = 1;
$loadStrings = 0;
$loadLocalVariables = 0;
$sourceDir = '/usr/home/sergio/tmp/src/AMARELA/4gl';
$replaceFgldoc = 0;
$fglSource = 'BdAmrCliente.4gl';
$logShowed = '1';
$importFglLocation = '/usr/home/sergio/AMARELA/src/4gl';
$loadFilesRecursive = '1';

Parser / Loader

Corresponde a um programa executável que trata de efectuar um parsing (com análise léxica e sintática) do programa fonte em 4gl e respectivos comentários especiais.

O nome do executável é p4gl.

Permite as seguintes opções de execução:
  •   -h : Mostra a mensagem de help
  •    -d : Indica que se pretende ligar o debug mode que efectua um dump da informação carregada
  •    -i : Indica que o programa deve inserir no repositório 
  •    -v : Indica se o modo verbose deve ou não ser ligado
  •    -w : Warning level (1..10)
  •    -c : Gera a informação html para este módulo especifico
  •    -s : Indica que se pretende carregar a informação contida em comentários normais (não começados com {**).
  •    -p package : Package name used to load the information
Este executável é, sob o ponto de vista da utilização da documentação, a parte mais importante. Quando um projecto estiver correctamente organizado e estruturado, a documentação será realizada pelos programadores em cada programa fonte e carregada para o repositório usando esta ferramenta.

O parser está implementado, tal como grande parte dos 4gl(s) existentes (exceptuando o da Informix e 4js) no que se refere às palavras reservadas.

Desta forma, deve ser carregada informação sem usar palavras pertencendes a statements de 4gl como nome de identificadores (ex: não usar display como nome de variável).

Se tal ocorrer e mesmo assim se pretender efectuar o carregamento da informação destes programas pode-se usar mais um comentário especial que, ao ser inserido faz com que o parser ignore o código entre ele inserido. O comentário especial é {IGNORE} e ignora o código até encontrar de novo um comentário igual.

Quando se tentar carregar informação com estas palavras reservadas sem que esteja no meio dos comentários IGNORE, o parser alertará a existência de um erro de sintaxe.

Repositório

O repositório reside numa base de dados devidamente normalizada e que tem de ser suportado por um SGBD informix.

É provavel que numa próxima versão possa funcionar com outro qualquer SGBD.

No manual de documentação técnica apresenta-se a informação mais detalhada e estruturada sobre o modelo de dados, no entanto de seguida apresenta-se um breve resumo das tabelas existentes e o significado do seu conteudo.

Tabela
Descrição
p4gl_excel
 Imagem do ficheiro CSV (registos com caracter separador) usado por carregamento de folha de cálculo.
p4gl_module
 Source 4gl no qual existe código programado.
p4gl_package
 Package. Abstração que irá permitir a unicidade de módulos e uma eventual classificação do mesmo. Poderá corresponder a uma aplicação ou directório.
p4gl_process
 Processos. Abstração que define o(s) processo(s) se negócio implementados pelo software.
p4gl_function
 Funções que estão implementadas em módulos.
p4gl_fun_parameter
 Parametros de execução de cada função declarada num módulo
p4gl_fun_process
 Processos de negócio que uma função implementa
p4gl_fun_return
 Valores de retorno devidamente identificados com comentários que uma função devolve
p4gl_fun_todo
 Lista de acções por realizar de uma função
p4gl_module_prog
 Módulos de 4gl que compõe o programa
p4gl_program
 Programa executável
p4gl_table_usage
 Utilização de tabelas em módulos e funções (para 4gl embebido não dinâmico)

Ciclo de refactoring de documentação 

A utilização da ferramenta permitiu-nos ganhar alguma experiência neste tipo de processos.

Assim, dadas as caracteristicas da ferramenta concluimos que esta nos permite fácilmente efectuar a documentação de um projecto em 4gl de uma forma iterativa e evolutiva.

Tal acontece pois é possivel efectuar importações e exportações em vários sentidos permitindo a sua modificação nos vários suportes em que ela vai sendo armazenada (CSV, SGBD, 4gl) podendo sempre ser convertida para outro formato (com excepção do html gerado que é unidireccional).

Assim, em nossa opinião, para documentar um projecto deve-se seguir os seguintes passos:
  • Carregar informação sobre os módulos para o repositório através de parsing : Nesta fase ficará guardado no repositório todas as funções dos módulos analisados com os respectivos parametros.
  • Gerar ficheiro CSV com esta informação.
  • Editar informação no Excel.
  • Completar a informação no repositório com base no ficheiro CSV editado no Excel.
  • Exportar a informação para os sources 4gl.
  • Alterar os comentários nos fontes 4gl
  • Efectuar o carregamento para navegação na informação.

Documentação de aplicação nova

Se uma aplicação fôr construida de novo, a equipa deve estar devidamente formada por forma a que a documentação seja inserida durante a fase de programação.

Assim, evitam-se refactorings desnecessários e aumenta-se bastante a facilidade de manutenção.

Se usada a lista de tarefas por realizar, pode ser uma importante ajuda no fluxo / processo de programação, dado que o programador irá registando nos sources que está a escrever (sem necessidade de mudar de ambiente) quais as tarefas que está a deixar para depois implementar (pois durante o desenvolvimento a nossa mente vai-se lembrando de pormenores que não se pode implementar na altura pois está-se a implementar outra funcionalidade).