Aprendendo a documentar o seu código

Quem desenvolve sistemas profissionalmente, sabe ou pelo menos deveria saber da importância de se documentar o código fonte. É preciso deixar claro que, por mais que utilizemos best practices em nossos projetos, se não documentarmos de forma eficiente os arquivos de código envolvidos, estaremos criando dificultadores para aqueles que receberem a incumbência de efetuar manutenções corretivas e evolutivas em nosso código no futuro.

Sabemos que muitos profissionais realmente não estão nem aí para a documentação dos projetos, alguns por não conhecerem os reais benefícios que um código bem documentado acarreta e outros por esperteza (leia-se burrice). Para aqueles que querem saber o que irá melhorar em suas vidas com a boa documentação do trabalho executado, preparamos este artigo. Já para os que se valem dos típicos sistemas “ninho de rato” para cravarem raízes nas empresas e se sentirem insubstituíveis..., deixamos um recado de amigo: ninguém é insubstituível e mais dia menos dia, algum chefe com bom senso vai dizer: não quero mais esse sistema e nem esse “analista”, prefiro pagar mais caro e ter algo totalmente novo, com garantia de qualidade. Nessa hora, o “esperto” entrará para o grupo dos desempregados e para conseguir uma boa recolocação no mercado, terá que provar que é bom tecnicamente, que está atualizado e que pratica boas práticas de programação, pois as grandes consultorias estão cada vez mais intolerantes com aqueles que “engessam código” e não entregam documentação.

Quando desenvolvemos, precisamos pensar no próximo, pois nem sempre somos o “pai da criança”. Reflita sobre quantas vezes você já foi alocado em projetos onde o seu trabalho era realizar uma manutenção corretiva/evolutiva e não um desenvolvimento do zero. E mesmo quando somos, nada nos garante que não teremos dificuldade em mexer em um código complexo, seis meses depois.

Para evitar dores de cabeça futuras, nada melhor do que prevenir, o que neste caso se traduz por documentar. Neste artigo você será apresentado a um santo remédio que atua principalmente contra o stress: técnicas de documentação de código, a serem usadas nos projetos em ASP.NET de modo que possamos a qualquer momento gerar arquivos atualizados de documentação sem esforço adicional da equipe. Isto irá ajudar a você e a sua equipe, agradar ao seu gerente e impressionar o seu cliente...

Nota: O passo a passo para gerar a documentação automática será descrito em um artigo a parte.

O que precisa ser documentado

Para explicarmos o que precisa ser documentado, tomaremos por base projetos escritos em C#, mas tenha em mente que o que explicaremos a seguir é válido também para outras linguagens .NET como VB.NET.

Os arquivos de código .cs devem ser documentados utilizando a técnica de documentação inline usada pelo Visual Studio. Estes arquivos em especial serão usados como origem para a criação dos arquivos .xml que contém os comentários que efetuamos em cada classe documentada e que por sua vez serão usados por ferramentas como o NDOC e o SandCastle para gerar a documentação dos projetos usando o mesmo formato adotado na MSDN.

Como documentar

A forma de documentar depende do tipo de arquivo que estamos construindo. Nas próximas seções, listamos os principais que precisam ser documentados, seja para geração automática de documentação externa, seja para facilitar o nosso trabalho em equipe.

Arquivos de classe

Nos arquivos .cs devemos utilizar a estrutura de documentação gerada de forma automática para cada classe e para seus membros. Basta posicionar o cursor de inserção na linha acima da linha em que começa a declaração do tipo ou membro do tipo que estamos documentando e teclar ///. No exemplo a seguir, devemos posicionar o cursor na linha 14:

E a seguir teclar ///. Isto fará com que o Visual Studio gere automaticamente o esqueleto em xml da documentação para aquele elemento que estamos documentando.

Devemos preecher a linha 15 com uma explicação sobre o motivo de existência da classe:

É interessante notar que o trecho de código gerado é sensível a assinatura do membro que estamos documentando, ou seja, se estivermos explicando o funcionamento de um método que aceita vários parâmetros e possui um valor de retorno, o xml gerado conterá elementos onde podemos detalhar cada um dos parâmetros fornecidos e o valor retornado.

O esqueleto de xml gerado contém o mínimo de código necessário para documentação. Dependendo da situação, é possível que precisemos incluir outras tags XML no cabeçalho. Para tanto, vá para a última linha do trecho da documentação (no exemplo, final da linha 26) e tecle Enter. Isto fará com que seja gerada uma nova linha:

Tecle < para que o intellisense forneça uma lista de tags suportadas pelas ferramentas de documentação:

Um exemplo frequente seria o de adicionar um comentário usando a tag <remarks> ou um link de arquivo a ser consultado usando a tag <see>.

manutenções futuras e até mesmo para nos guiarmos durante a construção. Para comentar, utilize os delimitadores . Os comentários inseridos desta forma não serão importados pelas ferramentas de geração de código e servem apenas para facilitar o nosso trabalho.

Arquivos de script .js

Nos arquivos de código javascript (arquivos .js) criados com versões anteriores ao Visual Studio 2008, devemos incluir comentários nos trechos de código que não sejam intuitivo e no cabeçalho dos métodos criados usando a marcação //. Os comentários inseridos nestes arquivos não serão absorvidos pelas ferramentas de geração automática de documentação, embora já existam programas específicos capazes de extrair documentação a partir destes arquivos.

Para aqueles que já estão trabalhando com o Visual Studio 2008, existe a possibilidade de documentar o código javascript de forma semelhante a do C#, usando ///. Infelizmente, em nossos testes feitos com as versões beta 2 do Team Suite e do Web Developer, este recurso não estava ativo. Tão logo consigamos experimentá-lo, publicaremos um novo artigo abordando exclusivamente este tema.

Arquivos de Web services

Nos arquivos .cs (arquivos .asmx.cs no ASP.NET 1.x) usados para definir webservices, além da forma de documentar já explicada para arquivos .cs em geral, há alguns cuidados extras que facilitam bastante o trabalho de outros desenvolvedores ao fazerem uso dos web services que estamos criando. Para explicar os passos extras, vamos recapitular o que acontece quando criamos um novo webservice.

Ao criar um novo serviço, o Visual Studio irá gerar o seguinte esqueleto de código no arquivo service.asmx.cs:

Se testarmos este exemplo no navegador, veremos a seguinte tela:

Como você deve estar percebendo não há informação útil para o desenvolvedor além do nome dos métodos que o webservice disponibiliza. Para tornar mais fácil o consumo do web service, devemos fornecer uma descrição para a classe do Web service e uma para cada método que é marcado como [webmethod]. Note que esta descrição não é absorvida pelas ferramentas de geração de documentação, motivo pelo qual devemos inserir descrição tanto em XML quanto nos atributos que serão apresentados adiante.

As alterações que devem ser feitas no Web service para que o mesmo seja de fácil consumo são as seguintes:

1. Alterar o namespace temporário fornecido para o namespace por um que seja único e adequado para cada caso:

Original:

[WebService(Namespace = "http://tempuri.org/")]

Alterado:

[WebService(Namespace = "http://Unibanco.InvestShop/")]

Importante: o namespace fornecido aqui não precisa ser igual ao usado na codificação das classes.

2. Criar um webservice usando a opção do menu de contexto Add\New Item e escolher Web Service. Isso fará com que o Web Service seja criado com o nome correto e não como service.asmx.

3. Adicionar uma descrição para a classe tanto em xml quanto no atributo [Webservice] usando Description.

4. Usar Description para documentar também os métodos.

Depois de efetuar as mudanças descritas, experimente executar a pasta de teste do Web Service no navegador:

Clicando no método disponibilizado pelo web service de teste, teremos a seguinte tela:

Como renomear um Web service já existente

Para renomear webservices que tenham sido criados com o nome de service.asmx (opção default quando se cria um projeto do tipo webservice) execute os seguintes passos:

a) Renomeie o nome da classe de service e do seu construtor para um nome adequado.

Original:

public class Service : System.Web.Services.WebService

Alterado:

public class Balance : System.Web.Services.WebService

b) Renomeie o nome do arquivo .asmx e o .cs presente na pasta App_Code.

c) No código do arquivo .asmx, modifique os parâmetros Codebehind e Class da diretiva Webservice:

Original:

<%@ WebService Language="C#" CodeBehind="~/App_Code/Service.cs" Class="Service" %>

Alterado:

<%@ WebService Language="C#" CodeBehind="~/App_Code/Balance.cs" Class="Balance" %>

Como comentar trechos de código

Embora não faça parte da documentação em si, é importante que você saiba que pode comentar parte do código que esteja dando problema para executar a aplicação antes de corrigí-lo. Os botões de comentar e descomentar presentes na barra do Visual Studio são sensíveis ao tipo de código em edição e mesmo ao bloco de código em que estamos. Isto significa que você pode comentar um trecho de forma adequada, simplesmente selecionando o mesmo e clicando no botão a seguir.

Podemos usar este recurso em:

arquivos .aspx _ pode ser usado para comentar por exemplo todo o trecho referente a um gridview, gerando o que é conhecido como comentário server-side.

arquivos .cs _ são inseridos comentários de uma linha para cada linha do bloco.

arquivos .config _ são inseridos comentários HTML/xml, o que permite termos por exemplo múltiplas configurações desabilitadas e uma ativa e chaveá-las com facilidade.

Arquivos .js _ são inseridos comentários de uma linha para cada linha.

Importante: não esquecer de remover depois, o código considerado obsoleto comentado. Isto tornará os arquivos menores e mais fáceis de se dar manutenção.

Conclusão

Documentar o código é vital para trabalharmos em equipe, pois facilita para quem está entrando na empresa e diminui o tempo de passagem de conhecimento, além de facilitar as manutenções. Um projeto bem documentado costuma ter uma vida útil muito maior, pois incentiva a reutilização de código e evita que os desenvolvedores percam tempo reinventando a roda ou tentando se localizar.

Como se todos esses argumentos por si já não bastassem, o Visual Studio ainda utiliza a documentação XML para fornecer descrição para o Intellisense, o que facilita em muito a programação. Veja a descrição de um método:

E a descrição de cada um dos parâmetros:

Percebeu o quanto isto torna a programação produtiva?

Abraços e até a próxima!

Cláudio Ralha
MCP - MCAD - MCTS
Palestrante Microsoft .NET Brasil
Líder do grupo Autores MS
Membro do conselho do grupo CommunityXtreme
Membro do grupo Code4All
Membro do grupo CsharpBR

Desenvolvimento - ASP. NET

Leia também