No dia a dia como desenvolvedor, nos deparamos diariamente com algumas dezenas ou centenas de linhas de código. Classes, funções, bibliotecas complexas muitas vezes desenvolvidas por terceiros e que precisamos conhecer para aproveitar completamente suas funcionalidades.
Quando se trata de uma pequena classe, com algumas poucas propriedades e métodos, pode ser bastante simples analisar sua estrutura e rapidamente compreender todo seu funcionamento. Porém, quando lidamos com classes mais extensas ou conjuntos delas (bibliotecas), ler o código fonte sempre que precisarmos saber a função de algum campo passa a ser uma tarefa bem custosa. Além disso, nem sempre é possível analisar o código fonte de uma biblioteca, pois nem todas são de código aberto.
Diante disso, é fácil perceber a importância de uma boa documentação de código, que forneça àqueles que vão ler o código posteriormente as informações necessárias para sua compreensão e melhor utilização. Um código bem documentado pode garantir maior produtividade e redução de erros, uma vez que o programador não precisará tentar adivinhar a função de uma propriedade ou método e nem sempre terá de analisar o código fonte para conhecer seu funcionamento.
Documentação de código no Visual Studio
O Visual Studio oferece um poderoso recurso de documentação que permite descrever propriedades, métodos e seus parâmetros, exibindo isso no intellisense ao se tentar acessar um campo documentado. Para demonstrar como funciona a documentação de código no Visual Studio, vamos criar uma pequena aplicação de exemplo, que pode ser de qualquer tipo, mas que neste artigo será uma Console Application, devido a sua estrutura simples e adequada para fins de didática.
Clicando com a direita no projeto dentro do Solution Explorer, acesse o menu Add > Class. Informe o nome da classe, que aqui será LivroCaixa, simulando uma parte de um sistema de controle de caixa.
Na classe criada, crie um método de sua preferência como o que é exibido na Listagem 1.
Listagem 1: Classe com método simples sem documentação
public class LivroCaixa
{
public void RegistrarMovimento(string historico, double valor)
{
Console.WriteLine("Movimento adicionado: {0} | {1}",
historico,
valor.ToString("#,##0.00"));
}
}
Ao tentarmos utilizar essa classe na nossa aplicação, neste caso dentro da classe Program, não temos nenhuma informação sobre seu funcionamento. O intellisense do Visual Studio apresenta apenas a descrição padrão para a classe e para seu método, como vemos nas Figuras 1 e 2.
Figura 1: Intellisense para a classe não documentada
Figura 2: Intellisense para o método não documentado
Supondo que estamos vendo esta classe pela primeira vez e ela não foi desenvolvida por nós. Como saberemos, por exemplo, como fazer para registrar no livro caixa uma despesa, ou seja, um movimento “negativo”? Neste ponto fica claro como uma boa documentação no código faria a diferença. Observe que já estamos perdendo tempo procurando saber como realizar uma operação aparentemente simples, mas que por falta de documentação, fica impossível saber ao certo como realizar. Voltemos então à classe e vamos corrigir esse problema.
Para adicionar a descrição a um método, classe ou propriedade, basta posicionar o cursor na linha acima da sua declaração e digitar /// (três barras seguidas). O Visual Studio irá automaticamente completar o código, identificando que ali será inserida a documentação daquele item.
Façamos isso na classe LivroCaixa. Insira um linha em branco sobre a declaração de classe, posicione ali o cursor e digite ///. Serão inseridas as marcações <summary> e </summary>, entre as quais você deve inserir a descrição da classe.
Repita o processo sobre o método RegistrarMovimento. Observe que dessa vez, além do summary foram inseridas duas marcações do tipo param, cada uma indicando o nome de um dos parâmetros do método. Entre elas você deve adicionar a descrição de cada parâmetro.
Após realizar os procedimentos descritos acima, a classe deve ficar semelhante ao que é exibido na Listagem 2.
Listagem 2: Classe e método documentados
/// <summary>
/// Classe responsável por regitrar movimentações no livro caixa do dia atual.
/// </summary>
public class LivroCaixa
{
/// <summary>
/// Método que registra um movimento no livro caixa.
/// </summary>
/// <param name="historico">Descrição do movimento.</param>
/// <param name="valor">Valor do movimento (utilizar valores negativos para despesas e positivos para receitas) </param>
public void RegistrarMovimento(string historico, double valor)
{
Console.WriteLine("Movimento adicionado: {0} | {1}",
historico,
valor.ToString("#,##0.00"));
}
}
De volta à classe Program, vamos novamente criar uma instância da classe LivroCaixa. Agora o Visual Studio exibe a descrição dessa classe (Figura 3), de acordo com o que definimos anteriormente. O mesmo ocorre com o método RegistrarMovimento (Figura 4).
Figura 3: Intellisense para a classe já documentada
Figura 4: Intellisense para o método documentado
Ao digitarmos o nome do método e abrirmos um parêntese, conseguimos ver a descrição dos parâmetros. E à medida em que vamos inserindo os argumentos solicitados pelo método, a descrição do próximo parâmetro é automaticamente exibida, como vemos na Figura 5.
Figura 5: Descrição dos parâmetros do método
É fácil perceber que agora aquele suposto problema sobre como lançar uma despesa foi resolvido, pois consta na descrição do parâmetro valor que devemos informar valores negativos para despesas e positivos para receitas.
Conclusão
Uma boa documentação, como já foi dito, pode garantir maior produtividade, redução de erros e, consequentemente, um produto com mais qualidade e entregue em menos tempo, o que implica em maior satisfação do cliente e, se for o caso, maior lucro.
Quando desenvolvemos códigos que inicialmente só serão utilizados por nós mesmos, é comum não nos preocuparmos com a documentação. Porém, como não sabemos o que ocorrerá no futuro, outra pessoa pode precisar utilizar nosso código ou ainda, nós mesmos podemos acabar esquecendo ou confundindo o funcionamento de uma classe ou método.
A documentação de um item não precisa ser demasiadamente extensa, e nem deve, ela deve ser concisa e clara o bastante para ser compreendida rapidamente.
Concluímos então que vale a pena gastar um segundo a mais para documentar nosso código, tarefa que fica ainda mais simples quando utilizamos os recursos do Visual Studio.
