12

Existe uma forma correta de comentar um trecho de código? Por exemplo:

// Esconde a tela
this.Hide()

ou seria:

this.Hide()
// Esconde a tela

ou até:

this.Hide() // Esconde a tela

Existe algum tipo de convenção para tal?

3
  • 1
    Talvez não. Veja se ajuda em algo: msdn.microsoft.com/en-us/library/ff926074.aspx#Anchor_2
    – stderr
    Commented 20/09/2016 às 14:01
  • Está dizendo sobre a posição de colocar ele? Tem que ser esse exemplo?
    – Maniero
    Commented 20/09/2016 às 14:04
  • 1
    Sim, existe - A previamente escolhida pela equipe de desenvolvimento, se você está trabalhando com uma. Caso não, sinta-se livre para escolher.
    – OnoSendai
    Commented 20/09/2016 às 14:06

2 Respostas 2

12

Não consigo imaginar um caso em que um comentário embaixo do fato seja útil.

É óbvio que comentários na mesma linha só podem ser feitos se o texto for muito curto.

Quando aprende quando comentar percebe que o comentário em código de produção raramente é útil se for posto na mesma linha. Não tem espaço para explicar o porquê daquilo. Em um protótipo, exercício, algo didático é diferente.

Então colocar logo acima costuma ser mais adequado. Isso é reforçado em C# pelo guia de convenções da Microsoft, postado em comentário acima do stderr. Nem mesmo eles seguem isso sempre. Bons programadores sempre entendem o contexto e sabem quando usar uma convenção e quando evitá-la.

Note que precisa analisar outras convenções também. Tem quem determine um tamanho máximo para as linhas. Outros não impõem esse limite e deixam a quebra de linha resolver isso.

Quando se comenta na própria linha sabe-se que é referente àquela linha. Quando se comenta acima não é certo até onde o comentário vale. Como os comentários precisam explicar algo mais amplo, é comum ser mais interessante colocar logo anterior ao que vai ser explicado.

Claro que você pode ter sua própria convenção. O importante é ser consistente.

Mas estamos falando de comentários fixos. Não é a mesma coisa de um comentário rápido, o chamado comment out, que se faz para tentar algo sem uma parte do código (coisa que deveria ser realmente algo bem temporário). Comentários temporários dependem muito da necessidade. É comum usar mais o /* ... */. Mas um // para eliminar o final da linha, possivelmente colocando uma outra parte no lugar pode ser o mais simples a fazer. O fato que se não vai sobreviver, e não pode mesmo, não importa muito, fica uma coisa bem pessoal.

Não comentar

Mas o ideal nesse caso é não comentar. O exemplo não é bom. Em outro contexto poderia ser que algum motivo especial definisse melhor a escolha.

O código comentado é óbvio, pelo menos no contexto geral do desenvolvimento.

Comentário sempre deve dizer porque aquilo foi feito e não o que foi feito. E só deve dizer o porquê se tiver um bom motivo. Se for dizer o que foi feito, conserte o código para ficar legível nele.

Comentários ficam defasados em relação ao código. É comum o programador mudar o código e esquecer de mudar o comentário. De uma certa forma viola o DRY de código. E eles incentivam as pessoas escreverem códigos menos legíveis.

Claro que em códigos didáticos, um comentário dizendo o que está fazendo até faz algum sentido, mas teria que ser bem explicativo. Não simplesmente repetindo o código. Nesse caso pode ser que o comentário inline seja mais adequado.

Não vou entrar em detalhes, já existem perguntas sobre isso:

Coloquei no GitHub para referência futura.

1
  • 1
    Achei super interessante sobre o post, algo bem completo como poderíamos usar e abusar dos comentários sem parece fora do formalismo didático de regras que regem a programação. Commented 8/12/2022 às 22:24
10

A especificação da linguagem C# não define um padrão de codificação. No entanto, as diretrizes são usadas pela Microsoft para desenvolver amostras e documentação.

As convenções de codificação atendem às seguintes finalidades:

  • Criam uma aparência consistente para o código, para que os leitores possam se concentrar no conteúdo e não no layout.

  • Permitem que os leitores entendam o código com mais rapidez, fazendo suposições com base na experiência anterior.

  • Facilitam a cópia, a alteração e a manutenção do código.

  • Demonstram as práticas recomendadas do C#.

Comentários:

  • Coloque o comentário em uma linha separada, não no final de uma linha de código.

  • Comece o texto do comentário com uma letra maiúscula.

  • Termine o texto do comentário com um ponto final.

  • Insira um espaço entre o delimitador de comentário (//) e o texto do comentário.

  • Não crie blocos de asteriscos formatados em torno dos comentários.

Exemplo:

// The following declaration creates a query. It does not run
// the query.

Referência: Convenções de codificação em C#

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .