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

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?

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ô'.

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.

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ê".

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.

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)

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").

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.

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.

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.

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.

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

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

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.

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.

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.

Pessoalmente, eu escreveria (em C #):

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

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