Os comentários em primeira pessoa são perturbadores e pouco profissionais?

63

Acabei de escrever o seguinte comentário em algum código (arcaico do Visual Basic 6.0) que estava escrevendo:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Não sei por que subconscientemente uso "nós" em meus comentários. Eu suspeito que é porque imagino alguém percorrendo o código, como se estivesse realmente "executando" todos os comandos em cada linha, em vez de apenas observá-los acontecer. Com essa mentalidade, eu poderia ter usado I can resize it, já que sou o que estou fazendo isso atualmente ou you can resize it, como se estivesse falando com quem está fazendo isso no futuro, mas como provavelmente esses dois casos provavelmente aconteça, eu uso "nós" como se estivesse liderando outra pessoa através do meu código.

Posso simplesmente reescrevê-lo it can be resizede evitar o problema, mas isso despertou minha curiosidade: é comum usar a primeira pessoa como essa nos comentários ou é considerado uma distração e / ou não profissional?

Dan Rasmussen
fonte
11
Comentários para o voto negativo? Esta é a minha primeira pergunta Programmers.SE, e ainda estou tentando descobrir exatamente o que faz uma boa pergunta P.SE versus uma boa pergunta SO.
precisa saber é o seguinte
2
Não votei contra você, mas pude adivinhar que eles não gostaram da pergunta do título, já que as respostas a ela poderiam ser facilmente curtas, tagarelas e excessivamente dadas a opiniões não apoiadas. Reescrever para que seja mais parecido com sua pergunta final pode ajudar.
DKnight
56
Eu gosto do 'nós'. É amigável e inclusivo de uma maneira saudável e folclórica.
Jeremy
25
Acho que vou começar a comentar todas as correções de erros em que eu trabalho na terceira pessoa, oniscientes, que devem me tornar popular no escritório ... "John pouco sabia que sua adição mal elaborada sempre ignoraria esse código, deixando os usuários perplexos. pelo campo de exibição perpetuamente vazio ... "
DKnight 08/07/11
4
É tudo o que posso fazer para garantir que meus comentários não ocorram erros de digitação. Agora, preciso me preocupar se a voz passiva deve ou não ser usada. Em seguida, terei que me certificar de que não mantenho nenhuma preposição - imagino que é algo que meus colegas talvez não aceitem. E suponho que nunca será permitido usar um infinitivo dividido. Fragmentos de frases?
Michael Burr

Respostas:

103

Comentários devem ser escritos para os seres humanos entenderem. Quando os seres humanos se comunicam, normalmente usamos "eu", "nós", "você" etc.

Quando alguém está tentando entender algum código, há dois ou mais atores: a pessoa que está lendo e o autor original do código. Dizer "nós" está bem. A menos que por 'profissional', você quer dizer 'semelhante a robô'.

whatsisname
fonte
3
Marcar como +1 dessa maneira incentiva o escritor a considerar o leitor em potencial e isso pode realmente ajudá-lo a ver conceitos que talvez precisem ser melhor explicados.
Justin Ohms
64
// we approve of this answer:)
Jarrod Dixon
3
+1 e uma amplificação: ao contrário, construções de voz passiva como "pode ​​ser redimensionado" são rejeitadas por escrito em geral, pois as achamos difíceis de entender. Se você usa voz passiva, força o seu leitor a inventar e lembrar um assunto para a frase.
msw
11
@ msw: não deveria ser 'rejeitamos construções de voz passiva como "pode ​​ser redimensionado" ...' então?
tdammers
2
@msw, em russo, por exemplo, construções de voz passivas são mais comuns e são mais facilmente compreendidas devido a algumas diferenças culturais. (E não, eu não escrever essa frase na voz passiva de propósito!)
P Shved
22

Eu sugeriria ficar longe de usar 'I' porque ele assume automaticamente toda a responsabilidade pelo código. Se outras pessoas estiverem lendo, pareceria ruim porque, nesse caso, é um esforço de equipe. Sou indiferente ao usar 'nós'. Pode, no entanto, parecer que inclui outros leitores de maneira genérica.

Meu voto ainda é conciso e conciso. Se a mensagem pode ser transmitida de maneira menos detalhada, por que escolher outra coisa? Então, nesse exemplo, eu escreveria:

'The form is not minimized so it can be resized safely.
Jonathan Khoo
fonte
4
"Se a mensagem pode ser transmitida de maneira menos detalhada, por que escolher outra coisa?" Como alguém que teve que bater com a cabeça na parede tentando implementar as bibliotecas mal documentadas de alguém - as bibliotecas de código aberto são notórias por isso - eu digo que preferiria ter muitos comentários do que muito pouco. Acho que concordo com você, se você quer dizer usar boas frases com pontuação correta que faça sentido.
Jonathan Henson
3
+1 por não assumir toda a responsabilidade em um ambiente de equipe. E, embora eu concorde em tentar evitar comentários detalhados, às vezes o tempo passivo pode ser ainda mais difícil de ler (como jkj apontou) e não menos detalhado, e prefiro evitar a ofuscação. =]
dlras2
2
@ Jonathan Henson: Muitos comentários são bons, mas apenas se eles contiverem muitas informações úteis. Se a mesma quantidade de informação puder ser expressa de duas maneiras equivalentes, a menor será melhor.
tdammers
Meu conselho é evitar o uso da voz passiva. É mais difícil de entender, especialmente para falantes de inglês não nativos.
Ville Laurikari
18

Eu tomo uma das duas abordagens, geralmente apenas o que soa melhor.

Ao explicar coisas como requisitos ou justificativas, eu vou com "nós" como você tem:

// We can't proceed unless the user has given us this information.

Se estou explicando o processo, costumo usar uma voz imperativa (comando) (me corrija se esse for o termo errado):

// Get the foo from bar and make sure it follows our required format.

O último pode chegar perigosamente perto de repetir o código, mas há usos. Portanto, não está usando eu ou nós, mas, na verdade, implica "você".

Tesserex
fonte
Este é exatamente o meu estilo também. As duas maneiras que você descreve têm o lugar delas.
zourtney
9
Este último tem "nosso" também. Acho interessante que as pessoas naturalmente escrevam comentários no plural na primeira pessoa.
Reid
@ Reid uau, sim, isso foi apenas instinto, eu nem percebi. Mas poderia ter dito facilmente "o".
Tesserex
8

Eu acho que é apenas uma variação no estilo de redação acadêmica / técnica, que geralmente é impessoal. Usando a voz passiva, usando o "nós real" ("um" é tão datado).

Como regra geral, não é específico quem o usará de qualquer maneira - o comentário é para o benefício dos mantenedores, normalmente não apenas para o autor original.

Dito isto, uso a primeira pessoa com bastante frequência nos comentários - para explicar por que tomei decisões específicas e o que estava pensando.

Steve314
fonte
3
Pessoalmente, não sinto que "um" seja datado. Sim, é de uso menos comum, porque não é algo que se usa de tempos em tempos. No entanto, há pouca ou nenhuma chance de que usar "um" nesse sentido de um comentário seja ilegível ou prejudique a usabilidade.
Billy ONeal
7

Os comentários devem dizer por que algo está sendo feito, não o que está sendo feito. Se o que está sendo feito não for óbvio no código, corrija o código, não basta adicionar um comentário. Primeira pessoa, segunda pessoa etc. não importam, o que importa é comunicar as informações necessárias.

Se você precisar narrar o código, prefira imperativos, por exemplo

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(E não use constantes nuas como "1" no código)

Steven A. Lowe
fonte
3
+1 por preferir o imperativo, eu não tinha pensado nisso. Além disso, sim, eu não deveria ter usado nada 1. Geralmente sou muito bom nisso ... Deixe-me publicar uma das poucas vezes em que isso me fez pensar na internet.
Dlras2
6

Talvez estejamos nos referindo aos rapazes do programa que fazem a mágica acontecer? :)

A voz passiva no idioma inglês é difícil de usar e soa mal. As pessoas gostam de usar formulários pessoais (eu, você, nós, um).

Exemplo:

(Você / nós / é preciso) usar um delegado para passar eventos de redimensionamento de janela para os pais

Um delegado deve ser usado para passar eventos de redimensionamento de janela para o pai

Outro exemplo (observe que muitas vezes você pode omitir os formulários da pessoa nos comentários):

(Nós) capturamos uma exceção. (Estaremos) mostrando uma caixa de diálogo de erro.

Uma exceção foi capturada e uma caixa de diálogo de erro será mostrada.

PS. Substituir passivo por "você" é tão comum no idioma inglês que também começou a vazar para outros idiomas. Parece extremamente engraçado, por exemplo, em finlandês, onde a forma singular da segunda pessoa existe (como o inglês "tu").

jkj
fonte
Eu acho que linguisticamente isso não está correto. O primeiro é o imperativo, ele não tem um assunto. "Por favor feche a porta." Enquanto isso significa aproximadamente o mesmo que "por favor, você pode fechar a porta?" é uma forma gramatical distinta, não uma abreviação. No segundo exemplo, você também poderia dizer "(Capturou) uma exceção. (Será) mostrando uma caixa de diálogo de erro".
Inca
3

Se você está falando sobre a execução do programa, não é 'nós', 'você' ou 'eu'. O antropomorfismo pode ser tão disseminado que passa despercebido, mas é um hábito perigoso (PDF Warning. Dijkstra Warning.):

Eu acho que o antropomorfismo é o pior de todos. Eu já vi programas "tentando fazer as coisas", "desejando fazer as coisas", "acreditando que as coisas são verdadeiras", "conhecendo as coisas" etc. Não seja tão ingênuo a ponto de acreditar que esse uso da linguagem é inofensivo. Convida o programador a se identificar com a execução do programa e quase obriga a usar a semântica operacional.

jaybee
fonte
2
Dijkstra Warning! Se apenas mais coisas tinha um :(
Tom Anderson
Não acho que escrever comentários no plural na primeira pessoa seja um antropomorfismo. Eu acho que isso implica: "Agora instruímos o computador a ...", como se o programador que escrevesse o comentário estivesse levando o leitor ao seu código.
blujay
2

Não acho que a primeira pessoa ou o "nós da realeza" pareçam pouco profissionais ou perturbadores. Eu acho que devemos fazer um esforço para escrever comentários em inglês no E-Prime , o subconjunto de inglês que não possui o verbo "ser".

Se você usa demais "ser" nos comentários, obtém declarações confusas como:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Bem, talvez não de uma só vez, mas a igualdade de direitos pode realmente tornar os comentários pouco claros.

Penso que os requisitos de escrita no E-Prime ajudam a torná-los mais claros, pois o escritor deve indicar um ator junto com a ação.

Bruce Ediger
fonte
Noção interessante; como alguém expressaria as noções de "X deve ser pelo menos 5" ou "Y não deve ser maior que 23"?
supercat
@supercat - "O valor de X deve ter magnitude 5 ou superior". "O valor de Y não deve exceder 23". Igualdade, lógica ou aritmética, também não deve usar o verbo "ser". "X deve conter 5" ou "X é avaliado como 5" ou "X tem o valor 5" ou algo assim. Se você se deparar com um comentário particularmente obscuro, procure verbos "ser". Aposto que esse comentário obscuro usa anotação, mas "para ser" verbos. Observe também que escrevi a resposta acima no E-Prime.
precisa
O segundo está bom; o primeiro nem tanto, já que -6 tem uma magnitude de 5 ou maior.
supercat
@ supercat - muito bem. "X deve ter um valor inteiro assinado igual ou superior a 5". Nos EUA, chamaríamos sua "magnitude" de "valor absoluto", o que reforça meu ponto de descrever o valor de uma variável, não a variável como valor, que surge da igualdade de oportunidades.
precisa
2

O estilo correto para comentar é a terceira pessoa impessoal; " O formulário não é minimizado, podendo ser redimensionado com segurança ".

  • Eu sou ingênuo.
  • Você é grosseiro.
  • Nós somos muito formais (e reais).

Cada frase pode ser reformulada dessa maneira (veja acima) e é a única maneira profissional de escrever.

user23157
fonte
11
-1 porque: não há uma maneira correta, acho o seu resumo de I / You / We um pouco fora de sintonia e não entendo a última parte. Além disso: quando digo "nós" nos meus comentários, não estou tentando falar como um rei - estou falando com você, o cara lendo meu código e conduzindo você pelos meus pensamentos lado a lado.
doppelgreener
2

Depende do comentário.

Normalmente, escrevo comentários da maneira sugerida por The Mouth of a Cow . Também sempre escrevo comentários geradores de documentação (Doxygen, JavaDoc) dessa maneira.

No entanto, muitas vezes negligenciam o uso do controle de versão para identificar quem escreveu / tocou linhas nos arquivos de origem. Há momentos em que dizer "eu" é apropriado, especialmente quando é bastante fácil rastrear o "eu" de volta para a pessoa que escreveu o código. Se você, como indivíduo, tomou uma decisão, recomendo usar "I" (junto com o controle de versão) para identificar e rastrear decisões alinhadas com o código.

Thomas Owens
fonte
+1 para Doxygen e JavaDoc. Concordo que a documentação é distinta dos comentários (embora alguns comentários gerem documentação) e faço o possível para manter essa documentação um passo mais formal do que meus comentários.
dlras2
1

Meu bom e velho pai (mhrip) perguntava: "Você não tem coisas mais importantes com que se preocupar?"

No entanto, pessoalmente, eu gosto do "nós". E também me pergunto por que escrevo em documentos upstream, nem mesmo em código, considerando que sou o único funcionário da minha empresa.

No entanto, eu e eu concordamos que desta maneira nos sentimos menos solitários :)

user18254
fonte
1

Eu sou o único que escreve "nós" e pensa "eu e o computador" (ou "minha equipe e o computador")? "Nós" vamos lidar com a solicitação que a parte externa nos deu, ou seja, "precisamos" ler a solicitação, abrir algumas janelas, fazer alguns cálculos com base nos "nossos" requisitos de negócios. Isso também ajuda a ver o código como parte do seu lado, não do inimigo :-)

Jan Fabry
fonte
0

Para comentários curtos, às vezes escrevo na segunda pessoa, como se estivesse instruindo outra pessoa, quase como uma mensagem direcionada ao próximo desenvolvedor para ler o comentário. Tal como

//You can get a session_id from SYSSession.getSessionID() if you need one

Comentários mais longos (como um cabeçalho de função longo ou várias linhas de descrição do algoritmo) Eu tento manter a neutralidade, sem primeira pessoa, segunda pessoa ou terceira pessoa.

FrustratedWithFormsDesigner
fonte
Inglês passive raramente soa bem: "A session_id pode ser obtido a partir de SYSSession.getSessionID () se for necessário"
jkj
0

Você adicionou este comentário porque o código não era suficientemente claro. Geralmente considero que expressar intenção por métodos bem definidos evita o uso de comentários. Por exemplo, essa linha de poderia ter sido movida para um método chamado CanThisFormBeResized.

Um método bem nomeado, por menor que seja, supera um comentário, porque é fácil para comentários e código ficarem fora de sincronia.

Portanto, se a maioria dos comentários pode ser expressa em código, isso deixa muito poucos motivos para comentários

  • Se seu comentário é sua opinião, comece com "I"
  • Se você acha que seu comentário deve ser uma opinião compartilhada (por exemplo, uma prática recomendada), comece com "nós"
  • Se o seu comentário é direcionado a algum código desonesto, escrito com uma meia-boca, então descarte o comentário, passe por cima dele e dê um soco no código confuso de um colega; então, fale com ele pessoalmente.
Steve Dunn
fonte
11
Desculpe, mas eu realmente não sou fã desse estilo. Especialmente porque esse código é usado uma vez, em um só lugar, e já é a única coisa no método de redimensionamento. Eu preferiria um comentário curto e bem redigido para aumentar a complexidade por meio da refatoração, especialmente ao trabalhar com o depurador VB6. Como um aparte, CanThisFormBeResizedprovavelmente deveria ser ThisFormCanBeResizedse vai ser usado assim If ThisFormCanBeResized Then.
dlras2
11
Essa é a preferência. Eu tomo um método booleano privado como function() { return this.windowState != 1 }sobre qualquer comentário. +1 de mim
keppla
11
@ Dan, e se alguém aparecer mais tarde: por que fazê-los procurar e redefinir a lógica para determinar se uma janela pode ser minimizada? Eles podem até não identificar sua pequena linha de código com um comentário e adicionar o seu próprio. Agora você tem 2 locais que precisam ser alterados se a lógica mudar e 2 locais onde os comentários podem ficar fora de sincronia com o código. Por que um método de 1 linha bem nomeado (que não muda de estado) adicionou complexidade? É a mais simples e uma das refatorações mais limpas que existem.
Steve Dunn
0

Como regra geral, sugiro usar a primeira pessoa, ou seja I,.

Por quê? Não por causa da natureza possessiva de eu, mas porque quando as pessoas falam em qualquer outra perspectiva, elas tendem a usar muitas palavras ou tornar as frases muito complexas e se perdem ao tentar explicar as coisas. A primeira pessoa tende a ser sempre mais fácil de ler.

Stephen Bailey
fonte
0

Pessoalmente, eu escreveria (em C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Ou algo nesse sentido, não precisando dos comentários.

Dot Net Pro UK
fonte
ResizeWindowSafelyimplicaria que pode ser chamado se você não souber se deve redimensionar ou não e, portanto, precisaria se incluir if (WindowState != WindowState.Minimised).
dlras2