O que você pensa sobre períodos / paradas completas nos comentários do código? [fechadas]

Vi isso perguntado no SO Tavern , então estou postando a pergunta aqui. Eu achei uma pergunta interessante. (É claro que não pertence ao SO, mas acho que está tudo bem aqui.)

Você adiciona pontos (ou, como o OP escreveu, "pontos finais") nos seus comentários de código?

Para mantê-lo relevante, por quê ?

Ponto final é para finalizar frases, mas se um comentário consistir em apenas uma frase cercada por código, ponto final não é necessário na minha opinião. Às vezes, nem uso maiúscula na primeira letra. Um comentário multilinha detalhado, por outro lado, precisa de pontuação completa.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}

Sim, porque os comentários estão em inglês e o inglês adequado usa pontuação.

Você adiciona pontos (ou, como o OP escreveu, "pontos finais") nos seus comentários de código?

Para mantê-lo relevante, por quê?

Pela mesma razão, eu os adiciono ao escrever um texto "normal" - eles fazem parte do idioma por escrito e não deve haver nada de especial sobre eles. Eu os uso igualmente ao escrever comentários de uma frase (uma linha) e parágrafos inteiros.

O código fonte não é um texto normal e, portanto, usamos regras diferentes para ele. Simples ;-)

Se você escrever comentários, espera-se que eles sejam escritos em inglês. Sendo esse o caso, deve-se pontuar corretamente. Fazer o contrário seria preguiçoso.

Se eu escrever uma frase completa (ou mais), então sim. Se não, às vezes não, mas geralmente ainda sim.

Às vezes eu também enlouqueço e uso pontos de exclamação, pontos de interrogação etc.;)

Quanto ao porquê, é em parte porque sou particularmente assim e em parte porque acho que a pontuação apropriada pode acrescentar muita clareza.

As outras respostas e sua popularidade deixaram claro que pontos finais são bem apreciados em comentários mais longos, e provavelmente podem ser evitados em frases simples.

Outro ponto que pode ser relevante é evitar pontos de exclamação, especialmente múltiplos . Exemplo:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

e

    // This code really sucks!

Por outro lado, pontos de interrogação são bastante úteis às vezes:

    // TODO: What does Crojpler.bway() actually do?

Depende. Se escrevo um parágrafo grande e apropriado explicando o que um bloco de código faz, então o pontuo corretamente, como qualquer outra parte da escrita apropriada. OTOH, quando apenas comento uma única linha de código, não o faço.

Por quê? - Semelhante ao motivo pelo qual escrevo e-mails usando a escrita adequada, enquanto posso usar frases abreviadas em mensagens SMS. Em um caso, estou sentado para escrever um bloco de texto adequado, então apenas "o faço corretamente" automaticamente, enquanto no outro é apenas uma breve nota para mostrar um ponto.

Exemplos reais do meu código:

Comentário rápido:

// check for vk_enter

Documentação do método "Adequado":

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.

Sim, acho que dessa maneira você cria uma boa convenção de codificação e também cria um código legível para uma terceira pessoa revisando seu código.

Vou sempre adequadamente capitalizar e pontuam ao criar comentários XML que eu esperava ser visto em IntelliSense e em nossa documentação gerada . Essas são construções muito mais formais e devem ser tratadas como tal.

Comentários apenas vistos no corpo de um bloco de código, no entanto, devem ser tão claros quanto possível. Cabe ao programador como eles conseguem isso.