Comentários - C#
Hoje vou falar um pouco sobre comentários em código C#, mas os conceitos podem ser aplicados a outras linguagens de programação.
Comentário pra quê?
Um código bem documentado é meio caminho andado para uma manutenção mais fácil. Óbvio que código comentado não necessariamente seja limpo, claro e de qualidade, mas os comentários ajudam a orientar uma pessoa programadora que possa vir a fazer a manutenção depois.
Então, principalmente na hora de criar algo do zero, é importantíssimo pensar em quem vai fazer a manutenção, essa pessoa pode ser inclusive você, então, comentários podem ser como post-its ou uma caneta marca texto e vão servir para demarcar coisas importantes ou indicar pontos de possíveis dúvidas ou melhorias.
O quê são comentários?
Comentários são partes de texto, que podem conter caracteres especiais e acentos, ou seja, se você quiser, pode escrever uma auto biografia nos comentários, isso não é o recomendado, mas você pode.
O mais importante dos comentários é que eles são ignorados pelo compilador, então caso você precise deixar uma parte de código comentado, isso não vai interferir em nada na compilação.
Para que o comentário seja identificado, alguns conjuntos de símbolos são utilizados para delimitar o que é comentário ou não.
Em C#, a notação mais comum é o uso de duas barras: //comentário. Além desse tipo de notação, também existe a demarcação: /*comentário*/.
Como posso usar comentários de uma forma clara?
Falando em desenvolvimento C#, caso você use o Visual Studio como IDE, existem atalhos muito práticos, inclusive para comentários. Como por exemplo, três barras em sequência: ///.
Ao digitar as três barras, um Sumário será gerado automaticamente como neste exemplo:
Comentários com este formato de Sumário são utilizados antes de um método. Ao digitar: /// na linha acima do método, os parâmetros existentes já são trazidos, com o nome que está na assinatura do método e o cursor já fica entre as tags:
///<summary>
///Cursor aqui :)
///Mais comentários
///</summary>
Caso seja necessário, linhas podem ser adicionadas entre as tags sendo iniciadas com /// e elas também farão parte do sumário.
Esse tipo de notação é utilizada para que os métodos sejam claros e legíveis antes mesmo que a pessoa precise expandir a sessão do método e ler o código de fato.
Um outro atalho do Visual Studio é o CTRL+M+O, esse atalho retrai todos os métodos e comentários no código, deixando visível uma lista com as primeiras linhas de comentários e as assinaturas dos métodos. Então, basicamente, se uma classe tiver vários métodos e todos tiverem um sumário, quem for fazer a manutenção pode ler essa lista e ter uma noção inicial da finalidade da classe em questão sem precisar logo de cara entrar no detalhamento de cada método.
O sumário é uma formatação de comentário que eu particularmente gosto e uso bastante, mas esta não é a mais conhecida ou a mais utilizada. A favorita é a //.
Uma linha de código iniciada com // sempre vai ser ignorada pelo compilador, mesmo que o que seguir essa notação seja um código válido como por exemplo:
Mesmo que no contexto este if seja válido, caso ele esteja depois de //, o compilador não vai considerá-lo.
Falando em Visual Studio, a cor utilizada para o texto dos comentários é bem destacada, o que pode ajudar na hora de ler uma classe.
As duas barras podem ser utilizadas após uma linha de código também, como no exemplo:
Normalmente este tipo de comentário, na mesma linha de uma ação, serve para esclarecer alguma coisa que possa estar ambígua no código ou para auxiliar na memória de quem está desenvolvendo. Esse comentário poderia ser por exemplo:
if(id == request.id)//Lembrar de conferir o retorno do request
Muitas vezes vejo que as pessoas tem medo de colocar comentários que não sejam bonitos ou que não tenham “um ar” de documentação. Mas a realidade é que os comentários devem ser capazes de conversar com quem está desenvolvendo. E a conversa muitas vezes precisa trazer detalhes que não estão claros ou que podem ser difíceis de identificar.
Por fim, falando em //, existe o tipo mais comum, que é a linha de comentário que indica ou explica uma ação do que a linha seguinte ou as linhas seguintes vão executar.
A outra notação que mencionei a cima foi: /*comentário*/. Diferente da //, esta notação demarca um intervalo de linhas do código que vai ser ignorado pelo compilador.
No exemplo a seguir o conteúdo dos comentários é o mesmo, tanto na parte que tem a notação: //comentário quanto na que tem a notação: /*comentário*/e ambos seriam ignorados pelo compilador na hora da execução.
A diferença é que a notação : /*comentário*/ requer um indicativo de início(/*) e um de parada (*/) circuncidando o comentário, essa notação pode facilitar a criação de um comentário como por exemplo, um bloco de código que você esteja estudando ou testando como no exemplo acima.
Com esta notação, não é necessário nenhum indicativo no início das linhas de comentário que estão entre os marcadores, diferente da notação com as duas barras (//) que só demarca o comentário de uma linha por vez.
Obviamente não é recomendado, em nenhuma situação, deixar um bloco de comentário com código não utilizado no meio da classe, isso deixa um lixo no código e pode confundir quem for dar a manutenção, então caso seja necessário deixar uma parte do código comentado temporariamente, tudo bem, mas é importante lembrar de passar pelo código e remover esse tipo de comentário depois, afinal, comentários servem para ajudar e não para confundir.
5 dos e 1 don’t (5 coisas para fazer e 1 para não fazer)
- Faça comentários claros que indiquem de fato o que é necessário.
- O sumário pode ser um tipo de comentário muito útil, especialmente em aplicações grandes ou que estão em expansão.
- Pense no comentário como um ajudante.
- Faça comentários que sejam claros e possam auxiliar na compreensão do código.
- Não tenha medo de comentar.
- Não deixe comentários que não fazem sentido ou pedaços de código comentados que não são mais utilizados no meio do fluxo, isso pode causar um gasto de tempo desnecessário só para identificar o que o comentário significa ou porque ele está ali.