Documentação de programas fontes

Documentação de programas fontes

Olá amigo(a),

Como toda obra bem planejada, o código fonte de um programa desenvolvido deve conter regras para que as futuras customizações possam ser realizadas sem colocar em risco o tempo de implementação. Os pontos a serem atacados são:

·       Padronização no nome do programa a ser desenvolvido

·       Documentação inicial do programa

·       Documentação das principais variáveis utilizadas

·       Padronização do nome das variáveis e parâmetros

·       Documentação de pontos importantes no decorrer do código

As principais metodologias de programação existentes atualmente indicam que cerca de 50% do código fonte deve estar documentado. É iminente que esse tipo de preocupação está relacionada ao entendimento do programa desenvolvido por toda a equipe, fazendo com que o conhecimento não fique centralizado apenas no autor do código.

No exemplo abaixo temos um programa fonte escrito em linguagem Oracle PL/SQL escrito com metodologia de programação.Nesse exemplo, a cada execução de um programa no banco de dados, o seu respectivo nome e a data/hora de execução são armazenados em uma tabela de log, o mesmo acontecendo no término de sua execução. Sendo assim, tem-se o tempo total de execução do programa. Isso é muito útil para saber o a quantidade de vezes e o tempo médio de execução de cada programa. Veja como esse programa está bem documentado.

create or replace procedure prc_inicio

(

p_num_seq_log    out number,

p_nom_processo   in varchar2

) is

begin

--------------------------------------------------------

-- Objetivo    : A cada programa a ser executado, a data

--                  de início é registrada junto com o nome

--                  do programa. Quando o processo finalizar,

--                  a procedure prc_fim entra em ação para

--                  armazenar a data de término

-- Autor        : Gustavo Padlipskas

-- Criado em : 01/10/2005

-- Parâmetros: p_num_seq_log -> É o número do log gerado

--                                         para indicar que o pro-

--                                         grama está executando.

--                                         Esse é um parâmetro de

--                                         retorno (saída)

--                                                                                                    

--                  p_nom_processo-> É o nome do processo que

--                                         está sendo executado. Esse

--                                         parâmetro é de entrada e

--                                         deve ser passado pelo

--                                            programador

--

--

--

--

-- Ultima Alteracao     Analista                  Descricao

-------------------------------------------------------------------

--  10/06/2006                Yuri Bello   Implementacao do controle

--                                                        de exceção do programa

--                                                                                                             

-------------------------------------------------------------------

-- 1o. passo -> gerar um número novo indicando o início de execução

select administrador.spmgaz_seq.nextval into p_num_seq_log from dual;

begin

 insert into administrador.spmgaz_log(num_seq_log, nom_processo, nom_usuario, dat_inicio )

 values ( p_num_seq_log , p_nom_processo, user, sysdate );

   commit;

exception   -- 10/06/2006 - Implementado um controle de exceção para

            -- tratamento de erro - (Yuri Bello)

  when others then

    raise_application_error( -20001, 'Erro Crítico * Insert log ' || SqlErrM);

end;

end prc_inicio;

No exemplo acima, o programador Gustavo Padlipskas escreveu um código padrão, utilizando:

(escritas em minúsculas, entrada de parâmetros iniciando-se com a letra "p", comentário no programa inteiro, etc). Quando existir a necessidade de se realizar a manutenção do programa, facilmente qualquer profissional que conheça a ferramenta terá facilidade em realizar novas customizações. Imagine todos os programas feitos na empresa utilizando padrões na programação. A facilidade no entendimento das variáveis seria enorme.

Atualmente, um dos principais custos na área de TI (senão o maior) está relacionado à equipe de desenvolvimento de software. Evitar a documentação de um programa fonte faz com que esse custo aumente, pois caso o membro da equipe responsável em fazer as customizações não tenha sido o autor original do programa, faz com que o tempo final da customização aumente consideravelmente.

Por fim, para que você seja sempre bem recomendado no mercado de trabalho pelos seus colegas de trabalho, documente muito bem seus programas e utilize um padrão, por mais simples irá agregar valor nas próximas manutenções. Ele é o seu cartão de visita permanente e conta um pouco de sua história pelas empresas as quais você passou.

Agradeceria de coração sugestões e comentários desse artigo para que seja possível replicar mais conhecimentos a todos nós.

Abraços,

Salvio