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ê ?
Respostas:
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.
fonte
Sim, porque os comentários estão em inglês e o inglês adequado usa pontuação.
fonte
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 ;-)
fonte
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.
fonte
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.
fonte
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:
e
Por outro lado, pontos de interrogação são bastante úteis às vezes:
fonte
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:
Documentação do método "Adequado":
fonte
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.
fonte
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.
fonte