C# – Documentado seu código2 min de leitura

Olá pessoal! Na grande maioria das linguagens de alto nível você irá possuir algum tipo de recurso que possibilita você criar comentários para o seu código. Comentário, como o próprio nome diz são blocos de texto livre que podem ser utilizados para documentar seu código, adicionar um aviso no código ou mesmo para “desabilitar” parte do código-fonte.

Propósito de um comentário

Antes de vermos os modos de se comentar em C#, vamos entender quais são os principais propósitos/motivos de usar um comentário:

• Documentar parte de um código complexo
• Comentar uma ou várias linhas de código que não devem se executadas temporariamente ou definitivamente

É bom deixar claro que um comentário não é compilado e tampouco executado.

Comentário inline

Criar comentário em C# é bem simples. Para o comentário inline, basta você colocar // (dupla barra) na frente do seu texto:

class Program
{
        static void Main(string[] args)
        {
             // Este é um comentário inline
             // Se precisar de mais de uma linha
             // Você vai ter que colocar mais barra dupla
        }
}

Comentário em bloco

Este tipo de comentário é bastante útil quando se deseja adicionar múltiplas linhas de comentário ou mesmo comentar um bloco de código, temporariamente:

class Program
{
        static void Main(string[] args)
        {
             /*
                 Data: DD/MM/AAAA
                 Descrição: este é um comentário em
                 bloco. 
             */
        }
}

No comentário em bloco, você irá abrir o bloco de comentário com /* e fechar com */ e tudo que estiver entre o bloco estará comentado.

Seu desafio: escrever código que não precise de comentário

Caso você esteja utilizando muitos blocos de comentário em seu código para documentar o comportamento do seu algoritmo, para e pense: será que estou escrevendo um código legível? Se seu código não está sendo capaz de descrever o que ele está fazendo sem que alguém explique o mesmo, talvez seu código precise ser revisado.

Um dos grandes desafios dentro da programação é escrever um código legível, que se auto documente. Portanto, tente sempre criar variáveis que tenham nomes sugestivos e que de fato descrevem o seu real propósito dentro do algoritmo. Evite criar:

• variáveis com nomes genéricos
• métodos que não execute de fato uma ação
• métodos com nomes que não descrevam a ação

Com essas três dicas, você talvez não use mais comentário com o propósito de documentar seu código. Logicamente, existe uma estratégia/técnica para tornar seu código limpo, mas isso vale uma postagem específica, pois o assunto é extenso. Porém, se quiser saber mais sobre como escrever um código limpo, indico aqui um bom livro sobre este assunto: Código Limpo: Habilidades Práticas do Agile Software (Robert C. Martin)

Por hoje, é isso pessoal!

Grande abraço!