Como você gosta de seus comentários? [fechadas]

Question

Quais são as suas melhores práticas para comentários? Quando eles devem ser usados, e que eles devem conter? Ou comentários mesmo necessário?

Answer 1

Os comentários são essenciais para a manutenção. O ponto mais importante a lembrar é para explicar Por você está fazendo algo, não O QUE você está fazendo.

Answer 2

Na escola, a regra era comentário tudo, tanto assim que os comentários superam código. Eu acho que isso é bobagem.

Eu acho que os comentários devem ser usados ??para documentar o "porquê" por trás de código, não o "como" ... o próprio código explica o "como". Se há uma operação que não é realmente clara de por que isso é feito, isso é um bom lugar para um comentário.

vezes de de TODO e FIXME ir em comentários, mas o ideal é que eles devem ir em seu gerenciamento de código fonte e ferramentas de rastreamento de bugs.

A única exceção de onde eu não me importo de comentários aparentemente inúteis é para geradores de documentação, que só vai imprimir documentação para funções que são comentadas - nesse caso, todas as necessidades de classe e interface API pública para ser comentado pelo menos o suficiente para se a documentação gerada.

Answer 3

O ideal é o seu programa pode se comunicar com o leitor de código e não nos comentários. A capacidade de escrever software que outros programadores podem entender rapidamente separa os melhores programadores da média em minha opinião. Normalmente, se você ou seus colegas não podem compreender uma secção de código sem comentários, que este é um "cheiro de código" e refatoração deve estar em ordem. No entanto, haverá algumas bibliotecas arcaicas ou outra integração que alguns comentários para guiar o desenvolvedor médio não é necessariamente ruim.

Answer 4

Como muitas vezes a resposta é: depende. Penso que a razão que você escreveu um comentário é muito importante para a decisão, se o comentário é bom ou ruim. Há várias razões possíveis para comentários:

• para tornar a estrutura mais clara (isto é, qual loop terminou aqui)

Bad: Isto parece um possível cheiro de código. Por que é o código tão complicado, que precisa de um comentário para esclarecer isso?

• para explicar o que o código faz

Muito ruim: Esta é, na minha opinião perigoso. Muitas vezes, isso vai acontecer, que posteriormente você alterar o código e esquecer o comentário. Agora, o comentário é errado. Isso é muito ruim.

• para indicar uma solução alternativa / a bugfix

Bom: Às vezes uma solução para um problema parece clara, mas a abordagem simples tem um problema. Se você corrigir o problema, ele pode ser útil para adicionar um comentário, por que foi escolhida esta abordagem. Caso contrário, outro programador depois pode pensar, que ele 'otimizar' o código e reintroduzir o bug. Pense sobre o Debian OpenSSL-problema. Os Debian-promotores removida uma variável não inicializado. Normalmente, uma variável não inicializado é um problema, neste caso, foi necessário para aleatoriedade. Um comentário de código teria ajudado a esclarecer isso.

• Para documentação-finalidades

Bom: Alguns documentação pode ser gerada a partir de comentários especiais formatado (ou seja Javadoc). É útil para documentar APIs públicas, que é um must-have. Importante é lembrar, que a documentação contém a intenção do código, não a implementação. Assim responde o comentário à pergunta 'Por que você precisa o método (e como você usá-lo)' ou que faz o método?

Answer 5

Eu acho que o novo movimento para remover comentários é ruim ... a razão, há um grande número de programadores que pensam que estão escrevendo fácil de entender código que não precisa de comentários. Mas, na realidade é apenas não é o caso.

Qual a percentagem de código de outros povos que você ler e entender instantaneamente .. Talvez eu li asp muito clássico, Perl e C ++, mas a maioria das coisas que eu li é complicado a roçar.

Você já leu o código de alguém, e tornou-se completamente confuso com isso. Você acha que eles pensavam enquanto eles estão escrevendo, isso é uma porcaria, mas eu realmente não me importo. Eles provavelmente pensou ohh ... isto é muito inteligente e vai ser SUPER rápido.

Answer 6

Apenas algumas observações:

Os comentários são importantes para tudo o que não pode ser facilmente inferida a partir do código (por exemplo, complexos algoritmos matemáticos).

Os problemas com os comentários é que eles precisam ser mantidos como o código, mas muitas vezes não são mantidos em tudo.

Eu não gosto comentários como este:

// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );

Melhor:

CreateAnalyzeButton();


void CreateAnalyzeButton()
{
    Button analyzeButton = new Button();
    analyzeButton.Text = "Analyze";
    analyzeButton.Location = new Point( 100, 100 );
    Controls.Add( analyzeButton );
}

Agora, o código de conta toda a história. Não há necessidade de um comentário.

Answer 7

Eu acho que depende do cenário.

Métodos / funções / classes precisam de uma breve descrição do que eles fazem, como eles fazem isso, o que tomar e que eles retornam, se não imediatamente óbvia e que normalmente (no meu código) vem na forma de um javadoc- estilo de comentário de bloco.

código no bloco, que tendem a deixar um comentário sobre um bloco de linhas para explicar o que faz, ou um no final da linha, se é uma curta e função-call enigmática.

Answer 8

Use a busca tag e você encontrará SO tem um monte de discussão sobre comentários de código já:

https://stackoverflow.com/questions/tagged/comments

Comentando código

Answer 9

Tenha um olhar em Code Complete . É simplesmente o melhor para tais temas.