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?
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?
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.
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:
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#