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

27

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ê ?

Moshe
fonte
2
Às vezes eu faço e às vezes não. Depende dos comentários e o que facilita a leitura.
Tim

Respostas:

29

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; 
}
mojuba
fonte
4
+1. Isso se parece tanto com o meu estilo de comentário que me deu um falso déjà vu. :)
Bobby Tables
26
Não, ponto final é para marcar o final das frases. É irrelevante se você tem um ou vários.
Rook
2
<piada> Não seria melhor verificar por exceder limites int </ piada>?
Dan Rosenstark
2
@ Yar: uma média é sempre entre aeb, que por definição estão sempre dentro dos limites, certo? ;)
mojubá
8
Todas as minhas strings são terminadas em nulo; portanto, um comentário adequado sempre deve terminar com '\ 0'. Você não quer que o próximo cara que está vendo seu código leia além do fim de sua mente, não é?
CodexArcanum
26

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

Dominique McDonnell
fonte
2
E as mensagens de texto?
Moshe
4
@Moshe, as mensagens de texto dificilmente são adequadas em inglês.
Dominique McDonnell
8
Dificilmente inglês adequado, mas ainda uso pontuação. A pontuação existe para orientar o leitor sobre exatamente o que o autor pretendia - isso se aplica a qualquer idioma, IMHO.
CjmUK
@cjmUK, Lol, sim e eu também. Pensei que Moshe quisesse dizer isso como uma razão para não usarmos pontuação, pois recebo regularmente mensagens como "aquele wd b gr8 cu lá tchau" que me levam até a parede
Dominique McDonnell
I nu wot u mento im wiv u tudo da maneira
cjmUK
17

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 ;-)

Torre
fonte
Um amigo meu nunca capta palavras em emails ... porque está na internet. Para mim, tudo bem quando você adapta sua escrita a limitações técnicas como o SMS, mas como os e-mails ou o código-fonte são diferentes do texto em cartas e livros?
LennyProgrammers
1
@ Lenny222 - Não sei o que você está perguntando aqui. Os emails devem ser escritos como texto normal; como se estivesse escrevendo uma carta como você diz. Como eles são realmente escritos (e SMSs, oh, garoto, não me inicie nos SMSs :) O código-fonte não se submete às mesmas regras que o texto normal, porque possui suas próprias regras de sintaxe.
Rook
2
Para mim, os comentários do código-fonte devem ser lidos por seres humanos. Por que deveria fazer a diferença se algumas informações estão em um documento de especificação separado ou incorporadas a um comentário de código-fonte?
LennyProgrammers
@ Lenny222 - Algo acabou de acontecer comigo, apenas para que não haja mal-entendidos entre nós. Agora estamos falando sobre o código fonte ou os comentários incorporados nele? Se for o segundo caso, peço desculpas, pois o entendi mal. Nesse caso, as mesmas regras aplicam-se ao texto normal (para comentários). No código-fonte real (aquele que é lido pelo compilador / intérprete), não vejo como as mesmas regras poderiam seguir.
Rook
1
Sim, acho que concordamos um com o outro sem saber. ;)
LennyProgrammers
9

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.

rapid_now
fonte
1
Os períodos são para o final de uma frase. Comentários não são necessariamente frases completas.
John B. Lambe
Os comentários, em geral, devem ser sentenças. Se não, eu deveria perguntar por que não. Se seus comentários são tão curtos que não são sentenças, talvez sejam óbvios e, portanto, supérfluos?
quickly_now
5

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.

Adam Lear
fonte
Se você estiver usando pontos de interrogação, entende seu próprio código?
Moshe
@ Moshe: Esses geralmente estão em TODOs quando ainda não entendo completamente meu próprio código.
Adam Lear
2
@ Moshe - Por que os comentários não podem incluir perguntas? As perguntas podem ser retóricas. Na verdade, muitas vezes nós? nos meus comentários - ao descrever código condicional, e não como uma explicação seca da lógica, geralmente é mais claro descrever a lógica como uma pergunta. Por exemplo, "Os critérios de qualificação foram atendidos? Se não, exiba um aviso ao usuário".
CjmUK
1
Ao trabalhar com grandes projetos e com muitos colaboradores, muitas vezes considero os comentários mais importantes.
LennyProgrammers
3

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?
Dan Rosenstark
fonte
1

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.
Bobby Tables
fonte
Desenvolvedor .NET, não é? ;-)
Moshe
@ Moshe: Java, na verdade. Este é o código de um applet muito grande e complexo, basicamente como um aplicativo Swing para desktop, exceto que é executado no navegador. :)
Bobby Tables
Eu acho que MDI é um termo .NET.
Moshe
@ Moshe: Nah, é genérico ( en.wikipedia.org/wiki/Multiple_document_interface ).
Bobby Tables
1

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
1
Que tal uma segunda pessoa?
daviewales
0

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.

Matt DiTrolio
fonte