Dicas para documentação de softwares

Necessidade ou preciosismo? A documentação de software mesmo sendo o carma de qualquer desenvolvedor, é extremanente necessária e auxilia na redução de horas preciosas na correção de problemas. Neste primeiro momento, vamos ver o que é a documentação de um sistema, suas partes principais e também as ferramentas que auxiliam desenvolvedores a fazer desta uma tarefa menos maçante.

Para muitos desenvolvedores a criação de documentação técnica é a parte mais aterrorizante para se enfrentar em todo o processo de criação de um software, seja pela necessidade de escrever várias e várias páginas de texto, gráficos e desenhos ou ainda pela necessidade de largar aquilo que se aprendeu (programar) para fazer aquilo que não sabe bem (redigir).

Entretanto a documentação é parte integrante de qualquer sistema ou programa criado. Arrisco a dizer inclusive que a documentação é tão importante (ou mais) que as questões de segurança pois sem a devida documentação, bug’s e pontos vulneráveis no sistema demoram a ser encontrados e corrigidos, permitindo assim que os ataques continuem levando à falência múltipla do sistema e, consequentemente, de seu usuário.

Normalmente em grandes corporações existem pessoas e/ou equipes voltadas única e exclusivamente para a criação de documentação, sendo que o desenvolvedor fica restrito à codificação e comentários de seu código. Já no mundo “real”, esta atividade é realizada pelo próprio 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. Então, como não é possível evitar a criação da documentação técnica, vamos tentar amenizar um pouco sua horrível aparência usando ferramentas que auxiliam na tarefa de domar o monstro. Mas antes disso, uma pequena apresentação do que é a documentação em si.

Documentação, o que é?

A documentação de um software é composta por várias partes diferentes que abrangem todo o sistema e pode ser dividida em dois grandes grupos: documentação técnica e documentação de uso. A primeira é voltada ao desenvolvedor ou pessoa de TI e compreende principalmente dicionários e modelos de dados, fluxogramas de processos e regras de negócios, dicionários de funções e comentários de código. Já a documentação de uso é voltada tanto para o usuário 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 informações que se deseja.

A primeira parte (técnica) é, para o desenvolvedor, a mais simples pois literalmente descreve seu trabalho e também é utilizada pelo mesmo como ferramenta para o desenvolvimento de um bom código. Já a segunda costuma ser um martírio pois a redação de manuais, inserção de screenshots, desenhos e outros elementos gráficos não é aquilo que podemos considerar como skill deste profissional (são raros os que possuem).

Ambas podem ser criadas em vários formatos de visualização tais como páginas HTML, documentos PDF, apresentações, vídeos ou ainda arquivos texto. A forma de apresentação não importa. O importante é saber que para cada tarefa existe uma ferramenta certa, inclusive para a documentação de sistemas em qualquer nível de complexidade ou necessidade e que precisa ser feita, de uma forma ou de outra.

As ferramentas para documentação

Aproveitando a divisão da documentação 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 documentação de sistemas.

Modelos de dados
Modelos de dados são aquelas folhas com várias caixinhas das tabelas de um banco de dados interligadas e que muitas vezes somente são utilizadas para decoração de escritórios. Mas longe de ser um quadro ou pôster, o modelo de dados reflete de uma forma gráfica (e lógica) 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 dicionário de dados, é peça fundamental para o desenvolvimento de um sistema, sendo inclusive pensado e criado ANTES do início do desenvolvimento. Um bom modelo de dados bem pensado e bem estruturado não impacta somente em um bom código, mas também na performace da aplicação com um todo e na redução de horas de desenvolvimento equivocado.

Para criá-lo são utilizadas ferramentas de modelagem de dados, as quais geram de forma gráfica 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 são o DBDesigner, MySQL Workbench e também o PGDesigner, as quais possuem funcionalidades diferentes e dispõem de versões tanto para Linux quanto para Windows.

Dicionário de dados
Como o próprio nome sugere, o dicionário de dados nada mais é que um arquivo ou documento que define a organização básica dos dados do banco. Nele são informadas as tabelas, os campos, suas definições, tipos e descrições (para que serve este campo?). Um exemplo simples de um dicionário de dados pode ser visto a seguir:

Campo	Tipo	Tamanho	Propriedades	Descrição
id_cadastro	Int	5	Auto-increment	ID do registro do cadastro
na_nome	Varchar	50	Not Null	Nome do dono da empresa
na_empresa	Varchar	50	Null	Nome da empresa
ad_email	Varchar	75	Not Null	Endereço de e-mail principal
nu_fone	Varchar	14	Not Null	Telefone de contato

Com um arquivo destes, mesmo simplório 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, além de economizar neurônios que muitas vezes estão sendo usados para armazenar a informação que o campo varCodSysFil01 é o código de uma filial.

Fluxogramas
Tão antigos quanto a computação, os fluxogramas apresentam graficamente a sequência lógica das informações de um processo ou sistema, utilizando para isso vários elementos de geometrias diferentes que indicam cada uma das partes do processo. Sua importância, mesmo deixada de lado, é grande pois a partir dele (e conjuntamente com o modelo e dicionário de dados), inicia-se o projeto de um sistema eficiente e bem desenvolvido.

Da mesma forma que o modelo de dados, fluxogramas são muitas vezes (mas não deveriam) utilizados como pôsters de escritório. Eles são mais que isso: visualmente conseguem passar a lógica de todo um sistema desde os níveis mais altos de processamento até pequenas partes, permitindo assim uma visão geral do que realmente precisa ser feito dentro do sistema.

Um exemplo de um fluxograma pode ser visto a seguir:

Para criar fluxogramas, as mais conhecidas ferramentas são: DIA e o OpenModeling, ambas disponíveis em várias plataformas e livres.

Documentação de código

Para muitos, a parte mais chata. Para outros, a mais importante. A documentação de código é feita basicamente de duas formas: comentários dentro do próprio código e geração de documentação online (ou física).

No primeiro caso normalmente o desenvolvedor acredita que sua memória nunca irá falhar e que somente ele irá colocar a mão no sistema, deixando de documentá-lo e gerando problemas gigantescos para sí e para outros profissionais. Um conjunto de cometários bem feito é tão importante quanto uma lógica bem estudada. Funções, constantes, inclusão 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 variáveis novas, pois não se recorda onde está aquela função que formata determinado campo (quem não passou por isso?).

Um pequeno exemplo de um código 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 não são necessárias dezenas de linhas de comentários para compreender o que determinada área do sistema executa. Mas se estas simples linhas forem deixandas de lado, além de gerar um gasto desnecessário de horas à procura de erros, aumenta-se o nível de estresse de todos que irão mexer no código e principalmente de quem paga por ele.

Para a criação de documentação de código online são utilizadas ferramentas que, baseadas nos comentários existentes dentro do código, permitem a geração de documentos que efetivamente explanam o sistema de forma macro, relacionando arquivos que são incluídos em outros, funções, seus parâmetros e retornos, constantes e uma infinidade de informações que auxiliam qualquer desenvovedor a compreender o que é aquele “monstro” nascido de suas mãos.

Mas isto é assunto para a próxima parte do artigo.