Artigo Clube Delphi Edição 50 - Documentação de Código Fonte

Documentação de Código Fonte

Utilizando o PasDoc e o DelphiDoc

Hoje em dia, muitas empresas de desenvolvimento de software adotam metodologias para construção e gerência de projetos de TI. Dentro desse processo, os desenvolvedores têm uma tarefa complexa e muitas vezes cansativa: criar a documentação.

Além da documentação do sistema (destinada ao usuário final), muitas vezes é necessário documentar também o código fonte, detalhando funções de units, classes, métodos, atributos, etc., que podem ser utilizadas por outros desenvolvedores e analistas do projeto. Quem nunca precisou perguntar a outro desenvolvedor da equipe algo do tipo: “o que você está fazendo nesse código?”, “o que faz esse método?” ou “qual a função dessa variável”.

Criar a documentação não é o maior problema, o difícil é mantê-la atualizada. Essa certamente é uma tarefa que a equipe “esquece” depois de algum tempo de projeto, visto que toda alteração no código precisa ser replicada na documentação.

Uma forma de tornar esse trabalho menos complexo e mais atraente para os desenvolvedores é “embutir” a documentação no próprio código fonte, utilizando comentários em um formulário especial. E depois, utilizar um software que seja capaz de interpretar esses comentários, gerando a documentação automaticamente (é exatamente isso que faremos aqui).

A importância da documentação do código fonte

As razões que temos para criar a documentação são inúmeras. Cito algumas:

·É muito mais fácil gerar a documentação do sistema (para o usuário final) se existir a do código fonte. Claro, outras documentações geradas em fases de definição e projeto também são importantes;

·Permite avaliar de forma rápida determinada funcionalidade do sistema, sem que seja necessário visualizar o código fonte ou conhecer seus detalhes internos. Isso é ideal, por exemplo, quando um Analista de Negócio precisa conhecer a funcionalidade de uma aplicação, sem necessariamente fazer isso do ponto de vista do programador;" [...] continue lendo...