As aplicações normalmente têm três tipos de documentos: especificações, documentos estruturais e manuais para os utilizadores.
O âmbito deste documento prende-se apenas com os documentos que descrevem estruturalmente as aplicações.
Documentação criada em documentos autónomos normalmente estão desactualizados e são modificados apenas quando a gestão o define como tarefa prioritária (o que apenas acontece quando o seu estado fôr tal que já não tem qualquer utilidade).
Desta forma pensamos que a melhor forma será a documentação estar a cargo dos programadores e de preferência junto do código que se está a documentar (ou seja no source de 4gl).
Por isso, a exemplo do javadoc decidimos criar uma ferramenta que com base em standards muito bem definidos extraia a informação embebida no código e gere documentos com formato especifico e perfeitamente definido.
Devemos portanto tentar seguir os seguintes principios:
A documentação estrutural é definida sob a forma de comentários de documentação escritos no código fonte e alguns documentos marcados como especificações acessiveis destes documentos.
Referências a alterações efectuadas em determinada versão devem ser mantidas no sistema de controlo de versões.
Os comentários não devem ser da exclusiva responsabilidade de nenhuma destas entidades. Esta é partilhada entre eles consoante a fase em que o projecto se encontra,
É importante notar que em grande parte dos projectos, os programas fonte são herdados já construidos e muitas vezes não documentados. De qualquer forma, de certeza não estão documentados com a nomenclatura que usamos.
Idealmente a documentação deve ser escrita pelos programadores à medida que implementam (ou alteram) as funções. Se existir uma metodologia de escrita inicial de um esqueleto sendo depois cada função implementada pelos programadores, deve ser o responsável pela construção do esqueleto a escrevê-lo.
Quando esta documentação é iniciada já depois da aplicação estar em funcionamento (num processo de refactoring ou simplesmente de documentação), deve ser efectuada sob a forma de empreitada tentanto ao máximo que seja o mais exaustiva possivel.
Após a documentação inserida, durante a fase de manutenção do projecto, os programadores têm de alterar toda a documentação no que refere às modificações efectuadas. No caso de resolução de bug(s) estas devem ser registadas no controlo de versões.
Com isto em mente, estes principios tentam descrever os comentários para documentação. Devem ser entendidos como sugestões em vez de requisitos rigidos a seguir até à exaustão. Sempre que existam alternativas criativas que se prove ser mais eficaz deve-se aplicáas e mesmo sugeri-las ao responsável deste documento.
Comentários para documentação (doc comments)
Comentários especiais escritos no código fonte de 4gl delimitado por {** ... }. Estes comentários são processados pela ferramenta p4gl paracarregar a documentação numa base de dados relacional. Desenvolvida em flex (lex), bison (yacc), C e perl.
fgldoc
A ferramenta que gera dinâmicamente a documentação a partir dos dados carregados no repositório em formato relacional. Foi desenvolvida em jsp e java.
A ferramenta gera documentação com origem em várias fontes:
Programas fonte em linguagem 4gl.
Documentos de descrição de processos.
Documentos de descrição de packages.
Um comentário de documentação é feito em duas partes: uma descrição seguido de zero ou mais tags, com uma linha em branco entre estas secções:
{**
Isto é a parte da descrição do comentário de documentação
@process ASSINANTES
}
|
A primeira linha é indentada por forma a estar alinhada com o código que segue o comentário e começa com o simbolo de inicio-de-comentário ({**) seguido de um return.
As linhas seguintes começam com um asteristico * ou apenas com um espaço. Quando existir, o asteristico é removido e substituido por um espaço.
Deve ser inserido uma linha de comentário em branco entre a descrição e a lista de tags tal como acima se apresenta.
Inserir linhas em branco entre blocos de tags relacionadas
A ultima linha começa com o simbolo de fim-de-comentário (}) seguido de um return.
Linhas com mais de 80 caracteres de comprimento devem, se possivel ser devidamente partidas. Se tiver mais de um parágrafo no comentário de documentação, separe o parágrafo com a tag <P>.
Primeira frase
A primeira frase de cada comentário de documentação deve ser um sumário, contendo uma descrição concisa mas completa do item que está a ser documentado. A ferramenta javadoc copia esta primeira frase para o sumário relativo do item. Isto torna importante a escrita de frases iniciais informaticas que se consiga descrever imediatamente.
Esta frase termina no primeiro ponto (.) seguido de um espaço, tab ou fim de linha ou na primeira tag encontrada. No exemplo que se segue a primeira frase termina em Prof.:
/** * Isto é uma simulação de experiência do Prof. Pardal. */
Se o preender, no entanto pode inserir um ponto usando os metacaracteres do HTML para conseguir este objectivo, como de seguida se define:
/** * Isto é uma simulação de experiência do Prof. Pardal. */
De seguida apresentam-se algumas sugestões e convenções para escritade das descrições nos comentários de documentação.
Usar <CODE> para palavras chave e nomes
As palavras reservadas devem estar entre as tags <CODE>...</CODE> quando mensionadas numa descrição. Incluir:
Palavras reservadas de 4gl
Nomes de funções
Nomes de variáveis (globais, locais e parametros)
Exemplos de código
Omitir parenteses para a forma geral das funções
Quando se referir no meio de um comentário a uma função deve sempre omitir os parenteses e os respectivos parâmetros. É preferivel incluir a palavra método quando se pretender usar.
Ex:
A função add permite inserir items. - Preferivel
add(item) permite inserir items Evitar
Usar expressões em vez de orações completas, no interesse da brevidade
Esta regra deve ser sobretudo aplicado quando se definem tags como por exemplo @param
Usar a 3ª pessoa (descritiva). Não a 2ª pessoa (prescritivo)
A descrição deve estar na 3ª pessoa declarativa em vez da 2ª pessoa impreativa.
Ex:
Devolve o número : Preferivel
Devolves o número: Evitar
Descrições de funções devem começar com expressão verbal
Um método implementa uma operação, assim normalmente começa com uma frase.
Obtem o nome do cliente : Preferivel
Esta função obtem o nome do cliente : Evitar
Adicionar descrições para além do nome da função
Os melhores nomes de funções auto documentam-se. No entanto, se o comentário apenas repetir o nome da função numa frase, não está a acrescentar qualquer informação. O comentário ideal vai para além das destas palavras e deve sempre recompensá-lo com mais um pedaço e informação que não é imediatamente (ou pelo menos para todas as pessoas) óbvia a partir do nome da função.
Ex:
Evitar -
{**
* Afecta o nome do cliente
*}
function setClientName(name)
Preverivel -
{**
* Regista o nome do cliente na variável modular para posteriormente o salvar na tabela clientes
*}
function setCliemntName(name)
Evite o latim
Use "tambem conhecido como" em vez de "aka", "ou seja" ou " sendo mais especifico" em vez de i.e.
As tags devem preferêncialmente ser incluidas na ordem que se segue:
* @author * @version * * @param * @return * @see * @since * @deprecated * @todo
De preferência dividir as tags por blocos relacionados.
Quando se inserir a mesma tag multiplas vezes deve-se separar das outras para aumentar a legibilidade.
Tags @param devem ter a mesma ordem que a ordenação correspondente do(s) parametro(s).
@author
Omitir se author desconhecido. Pode-se usar expansões efectuadas pelo controlo de versoes. Se existirem várias devem estar ordenadas por ordem cronológica.
@version
Pode-se, se possivel usar a expansão do controlo de versões. Corresponde à revisão do source e não à versão do executável resultado ca compillação de vários sources.
@param
Esta tag deve ser seguida pelo nome do parâmetro (não o seu tipo). Embora seja redundante com a declaração do(s) parãmetros, é a única forma de efectuar a associação de um comentário especifico com o parâmetro. Por convenção o primeiro substantivo da descrição deve reflectir o tipo de informação que este armazena (pode ser precedido por artigos como "O").
Ex:
* @param num o número a formatar * @param strUsing string de formatação do número
Não inserir entre tags <CODE> </CODE> pois a ferramenta de exploração já o faz.
Usar preferêncialmente uma expressão a uma oração.
@return
Em métodos que não retornem qualquer valor deve ser omitido.
Quando o método retornar diferentes valores devem exitir várias tags para cada tipo de retorno.
@deprecated
Permite marcar um método como de utilizaçao a evitar pois ira provavelmente desaparecer na proxima versao.
@since
Marca a versão (quando esta fôr conhecida) a partir da qual o método foi inserido.
Inserir apenas se conhecido e relevante
@todo
Define uma funcionalidade a implementar neste método. Permite ao programador marcar determinada tarefa que deve ser implementada na função, mas que não é oportuno implementar (ou porque está apenas a resolver um problema ou porque não pretende quebrar determinada linha de raciocinio).
Desta forma pode-se, em qualquer altura relembrar o que faltou implementar.