Estilo de codificação C #: comentários

A maioria dos guias de estilo C # recomenda contra o estilo de comentário / * … * /, em favor de // ou ///. Por que o estilo antigo deve ser evitado?

Eu não diria que tenho uma visão forte contra qualquer um – mas o maior problema da IMO é que /* e */ ficam confusos se você o aninhar, com o efeito colateral de não ser possível copiar / colar blocos ).

Você pode facilmente acabar com o código errado comentado / ativado, ou pode acabar com ele não compilando porque você acabou com um /* /* */ */ .

Se você copiar um bloco de // próximo, nenhum dano – apenas essas linhas permanecem comentadas.

Um exemplo que vem à mente é que é possível interromper acidentalmente um comentário no estilo /* . Por exemplo

 /* This is the start of a comment that documents the behavior of the +-*/ operators in our program */ 

Este código não compila, enquanto a // variante seria. Além disso, o /// representa um estilo específico de documentação para o qual as ferramentas externas respondem de maneira diferente.

Existem algumas razões para preferir // a / * .. * /.

  • Como JaredPar mencionou, há problemas estranhos de aninhamento de comentários que podem surgir com / * * / usage.
  • Se você alguma vez escreveu / escreveu algum código que processa arquivos de código fonte, você ficará realmente feliz se o // método é tudo o que você tem que lidar.
  • É muito mais fácil detectar visualmente um grande bloco de código comentado com o método “//”, especialmente se a coloração de syntax estiver indisponível. Na verdade, muitas vezes você verá as linhas individuais em um bloco / * * / prefixado com um *, só por segurança.
  • O estilo de comentário XML que pode ser usado para produzir documentação de código requer que “///” seja usado.

Uma coisa que / * * / pode fazer isso // não é comentar uma parte interior de uma linha. Às vezes, eu uso isso para comentar um parâmetro para um método em que algo não é óbvio:

  point = ConvertFromLatLon(lat, lon, 0.0 /* height */ ) ; 

Neste caso, a constante 0.0, sendo passada como o terceiro parâmetro, representa a altura. Claro que isso pode ser melhor:

  double height = 0.0; point = ConvertFromLatLon(lat, lon, height) ; 

(Eu estou mais propenso a usar o / * * / intra-line temporariamente, apenas para tentar passar um valor específico.)

/* */ é bom para blocos de código de várias linhas. Por exemplo, no topo de um arquivo de código, informações de direitos autorais etc.

// é mais fácil para uma única linha.

Sempre use /// para pelo menos todos os membros públicos em uma class, pois sua documentação XML é gerada a partir da qual você pode criar arquivos de ajuda.

Eu acho que você comentar como quiser, já que a maioria de nós está comentando através de atalhos no Visual Studio. Eu uso ctr+K, ctrl+C todas as linhas selecionadas são comentadas e ctr+K ctrl+U para descomentar linhas selecionadas.

Minha opinião é que “//” é mais fácil de digitar do que / ** /

Eu acho que /* */ eventualmente seguirá o caminho do Dodo, porque no Visual Studio você pode simplesmente selecionar um bloco de código e pressionar CTRL-E, C para comentá-lo usando o // estilo.

Eu sempre uso // para COMENTOS reais, enquanto eu salvo o / * * / para o código que eu temporariamente não quero executar para fins de debugging / desenvolvimento.

Usando apenas //, você pode ter certeza de que pode comentar um grande bloco de linhas / methods etc sem aninhar comentários e fazer seu compilador chorar.

Meu palpite é porque um requer syntax explícita em cada linha e um cria comentários que podem comentar grandes seções de código se o fechamento */ não é usado. Não é tão seguro.