A Importância de Comentar o Código Fonte

Tempo de leitura: menos de 1 minuto

Passamos a maior parte de nosso dia se não todo…rs  programando, digitando linhas e mais linhas de código, desenvolvendo para um projeto individual, ou em grupo, tempos prazos muito curtos isso se tivermos algum prazo  e muitas vezes, para economizar tempo deixamos de lado as boas praticas de desenvolvimento que muito ajudam tanto no desenvolvimento como na manutenção do código, tanto por nós mesmos, ou até mesmo por outros membros da equipe.

Neste artigo, vou tratar um pouco sobre a importância de se documentar o Código Fonte de sua aplicação, e como isso , embora demande certo tempo, pode nos ajudar no futuro.

 

Vamos imaginar que estamos desenvolvendo um sistema ERP, um ERP como todos sabem, é um sistema bem grande e complexo, com muitas regras.

Vamos imaginar ainda que temos um prazo muito, muito apertado mesmo, e que para economizar tempo em desenvolvimento a equipe decidiu não comentar o código naquele momento, e sim no futuro, após o projeto se encontrar em produção, assim como eu, você também sabe que essa documentação jamais ocorrerá  e assim, a equipe economizará muito tempo.

O sistema foi concluido, a versão foi para a produção, e depois de quase um ano, e parte da equipe renovada, o sistema necessita de uma atualização devido a uma nova legislação. O desenvolvedor abre a aplicação, vai ver oque determinado método deve fazer e então “voilà” não existe nenhuma explicação, nenhum comentário do que aquele método deve fazer, então, oque ocorre? Ocorre que agora, quando o sistema necessita de uma pequena manutenção, que poderia ser resolvida em apenas algumas poucas horas, pode levar dias para ser resolvido, pois o desenvolvedor vai ter que entender exatamente oque o método faz para que não danifique mais o sistema sem perceber.

 

Entendem agora, a importancia de se documentar o código fonte? É bem simples, deixa seu código mais limpo isso na minha opnião e quando necessitar de manutenções, você ou outro desenvolvedor não necessitará de uma bola de cristal para realizar a correção.

Veja a diferença de um código documentado, e um sem documentação quando estamos consumindo o método:

 

 

 

 

 

 

Exemplo de método Documentado

 

 

 

 

 

Exemplo de método sem documentação

 

Viram como fica bem melhor de se trabalhar quando o código está documentado?

A documentação do código é feita em XML, então é bem simples de se fazer, veja um módelo de documentação de um método:

        /// <summary>
        /// Método utilizado para atualizar o campo informado na base de dados
        /// </summary>
        /// <param name="_campo">Nome do campo a ser atualizado</param>
        /// <param name="_valor">Valor a ser atribuido no campo</param>
        /// <remarks>Método criado para exmplificar no artigo</remarks>

A Tag “Summary” é a utilizada para descrever o método em si;

A Tag “Param” é utilizada para descrever o/os parametro/os;

A Tag “Remarks” é utilizada para criar comentários adicionais sobre o método

Existem algumas outras Tag’s também, como por exemplo a Tag “exception” , onde você pode descrever que excessões seu método retornará para que seja experada ao consumir o método.

Quando sua aplicação estiver concluida, e toda bem documentada, você pode utilizar alguns aplicativos para gerar essa documentação para você , em forma de um helper, como por exemplo o “Sandcastle”, que é um aplicativo muito bom para isso, e está disponivel no CodePlex para Download.

http://shfb.codeplex.com/

Bom, pessoal, por enquanto é isso, espero que ajude a vocês, e caso tenham duvidas, é só entrar em contato.