Dicas para documentao de softwares

Postado em 13/07/2006 - 2 Comentrios

Necessidade ou preciosismo? A documentao de software mesmo sendo o carma de
qualquer desenvolvedor, extremanente necessria e auxilia na reduo de horas
preciosas na correo de problemas. Neste primeiro momento, vamos ver o que a
documentao de um sistema, suas partes principais e tambm as ferramentas que
auxiliam desenvolvedores a fazer desta uma tarefa menos maante.
Para muitos desenvolvedores a criao de documentao tcnica a parte mais
aterrorizante para se enfrentar em todo o processo de criao de um software, seja pela
necessidade de escrever vrias e vrias pginas de texto, grficos e desenhos ou ainda
pela necessidade de largar aquilo que se aprendeu (programar) para fazer aquilo que no
sabe bem (redigir).
Entretanto a documentao parte integrante de qualquer sistema ou programa criado.
Arrisco a dizer inclusive que a documentao to importante (ou mais) que as
questes de segurana pois sem a devida documentao, bugs e pontos vulnerveis no
sistema demoram a ser encontrados e corrigidos, permitindo assim que os ataques
continuem levando falncia mltipla do sistema e, consequentemente, de seu usurio.
Normalmente em grandes corporaes existem pessoas e/ou equipes voltadas nica e
exclusivamente para a criao de documentao, sendo que o desenvolvedor fica restrito
codificao e comentrios de seu cdigo. J no mundo real, esta atividade
realizada pelo prprio desenvolvedor e demanda um bom conjunto de horas para
planejar e criar cada uma de suas partes a fim de atender minimamente as necessidades
do produto desenvolvido. Ento, como no possvel evitar a criao da documentao
tcnica, vamos tentar amenizar um pouco sua horrvel aparncia usando ferramentas que
auxiliam na tarefa de domar o monstro. Mas antes disso, uma pequena apresentao do
que a documentao em si.

Documentao, o que ?
A documentao de um software composta por vrias partes diferentes que abrangem
todo o sistema e pode ser dividida em dois grandes grupos: documentao tcnica e
documentao de uso. A primeira voltada ao desenvolvedor ou pessoa de TI e
compreende principalmente dicionrios e modelos de dados, fluxogramas de processos
e regras de negcios, dicionrios de funes e comentrios de cdigo. J a
documentao de uso voltada tanto para o usurio final quanto para o administrador
do sistema e comumente formada por apostilas ou manuais que apresentam como o
software deve ser usado, o que esperar dele e como receber as informaes que se
deseja.
A primeira parte (tcnica) , para o desenvolvedor, a mais simples pois literalmente
descreve seu trabalho e tambm utilizada pelo mesmo como ferramenta para o
desenvolvimento de um bom cdigo. J a segunda costuma ser um martrio pois a
redao de manuais, insero de screenshots, desenhos e outros elementos grficos no

 aquilo que podemos considerar como skill deste profissional (so raros os que
possuem).
Ambas podem ser criadas em vrios formatos de visualizao tais como pginas HTML,
documentos PDF, apresentaes, vdeos ou ainda arquivos texto. A forma de
apresentao no importa. O importante saber que para cada tarefa existe uma
ferramenta certa, inclusive para a documentao de sistemas em qualquer nvel de
complexidade ou necessidade e que precisa ser feita, de uma forma ou de outra.

As ferramentas para documentao

Aproveitando a diviso da documentao em duas grandes reas, vamos conhecer suas
partes e algumas ferramentas que ajudam e/ou facilitam aqueles que tem pela frente a
tarefa de gerar documentao de sistemas.
Modelos de dados
Modelos de dados so aquelas folhas com vrias caixinhas das tabelas de um banco de
dados interligadas e que muitas vezes somente so utilizadas para decorao de
escritrios. Mas longe de ser um quadro ou pster, o modelo de dados reflete de uma
forma grfica (e lgica) a base de dados de um sistema, seus relacionamentos,
entidades, chaves e tudo aquilo que referente aos dados em si.
Este modelo, junto com o dicionrio de dados, pea fundamental para o
desenvolvimento de um sistema, sendo inclusive pensado e criado ANTES do incio do
desenvolvimento. Um bom modelo de dados bem pensado e bem estruturado no
impacta somente em um bom cdigo, mas tambm na performace da aplicao com um
todo e na reduo de horas de desenvolvimento equivocado.
Para cri-lo so utilizadas ferramentas de modelagem de dados, as quais geram de forma
grfica as tabelas, ndices, relacionamentos e tudo aquilo que tem a ver com a base de
dados em si, podendo ser criados por meio de engenharia reversa ou ainda baseando-se
nas necessidades do aplicativo que est sendo desenvolvido.
As ferramentas mais conhecidas para modelagem de dados dentro do mundo livre so o
DBDesigner, MySQL Workbench e tambm o PGDesigner, as quais possuem
funcionalidades diferentes e dispem de verses tanto para Linux quanto para Windows.
Dicionrio de dados
Como o prprio nome sugere, o dicionrio de dados nada mais que um arquivo ou
documento que define a organizao bsica dos dados do banco. Nele so informadas as
tabelas, os campos, suas definies, tipos e descries (para que serve este campo?).
Um exemplo simples de um dicionrio de dados pode ser visto a seguir:
Campo

Tipo

id_cadastro Int
na_nome

Tamanho Propriedades Descrio

5

Varchar 50

Autoincrement

ID do registro do
cadastro

Not Null

Nome do dono da
empresa

na_empresa Varchar 50

Null

Nome da empresa

ad_email

Varchar 75

Not Null

Endereo de e-mail
principal

nu_fone

Varchar 14

Not Null

Telefone de contato

Com um arquivo destes, mesmo simplrio em conjunto com o modelo de dados, a

possibilidade de erro na hora do desenvolvimento fica extremanente reduzida quando
falamos de acesso dados na base, alm de economizar neurnios que muitas vezes
esto sendo usados para armazenar a informao que o campo varCodSysFil01 o
cdigo de uma filial.
Fluxogramas
To antigos quanto a computao, os fluxogramas apresentam graficamente a sequncia
lgica das informaes de um processo ou sistema, utilizando para isso vrios
elementos de geometrias diferentes que indicam cada uma das partes do processo. Sua
importncia, mesmo deixada de lado, grande pois a partir dele (e conjuntamente com o
modelo e dicionrio de dados), inicia-se o projeto de um sistema eficiente e bem
desenvolvido.
Da mesma forma que o modelo de dados, fluxogramas so muitas vezes (mas no
deveriam) utilizados como psters de escritrio. Eles so mais que isso: visualmente
conseguem passar a lgica de todo um sistema desde os nveis mais altos de
processamento at pequenas partes, permitindo assim uma viso geral do que realmente
precisa ser feito dentro do sistema.
Um exemplo de um fluxograma pode ser visto a seguir:

Fluxo de documentao
Para criar fluxogramas, as mais conhecidas ferramentas so: DIA e o OpenModeling,
ambas disponveis em vrias plataformas e livres.

Documentao de cdigo

Para muitos, a parte mais chata. Para outros, a mais importante. A documentao de
cdigo feita basicamente de duas formas: comentrios dentro do prprio cdigo e
gerao de documentao online (ou fsica).
No primeiro caso normalmente o desenvolvedor acredita que sua memria nunca ir
falhar e que somente ele ir colocar a mo no sistema, deixando de document-lo e
gerando problemas gigantescos para s e para outros profissionais. Um conjunto de
cometrios bem feito to importante quanto uma lgica bem estudada. Funes,
constantes, incluso de arquivos, campos de tabelas e outros elementos sempre
proliferam de forma exponencial dentro do sistema, o que leva na maioria das vezes o
desenvolvedor a simplesmente criar novos remendos com constantes adicionais ou
variveis novas, pois no se recorda onde est aquela funo que formata determinado
campo (quem no passou por isso?).
Um pequeno exemplo de um cdigo bem comentado pode ser visto a seguir:
$database->setQuery( $query );
$rows = $database->loadObjectList();
// establish the hierarchy of the menu
$children = array();
// first pass collect children
if ($rows) foreach ($rows as $v ) {
$pt = $v->parent;
$list = @$children[$pt] ? $children[$pt] : array();
array_push( $list, $v );
$children[$pt] = $list;
}
// second pass get an indent list of the items
$list = mosTreeRecurse( 0, , array(), $children, max( 0, $levellimit-1 ) );
// eventually only pick out the searched items.
if ($search) {
Observe que no so necessrias dezenas de linhas de comentrios para compreender o
que determinada rea do sistema executa. Mas se estas simples linhas forem deixandas
de lado, alm de gerar um gasto desnecessrio de horas procura de erros, aumenta-se o
nvel de estresse de todos que iro mexer no cdigo e principalmente de quem paga por
ele.
Para a criao de documentao de cdigo online so utilizadas ferramentas que,
baseadas nos comentrios existentes dentro do cdigo, permitem a gerao de
documentos que efetivamente explanam o sistema de forma macro, relacionando
arquivos que so includos em outros, funes, seus parmetros e retornos, constantes e
uma infinidade de informaes que auxiliam qualquer desenvovedor a compreender o
que aquele monstro nascido de suas mos.
Mas isto assunto para a prxima parte do artigo.
Tags:documentao, programao, projeto, software