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 resized
e 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?
fonte
Respostas:
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ô'.
fonte
// we approve of this answer
:)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:
fonte
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:
Se estou explicando o processo, costumo usar uma voz imperativa (comando) (me corrija se esse for o termo errado):
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ê".
fonte
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.
fonte
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
(E não use constantes nuas como "1" no código)
fonte
1
. Geralmente sou muito bom nisso ... Deixe-me publicar uma das poucas vezes em que isso me fez pensar na internet.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:
Outro exemplo (observe que muitas vezes você pode omitir os formulários da pessoa nos comentários):
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").
fonte
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.):
fonte
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:
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.
fonte
O estilo correto para comentar é a terceira pessoa impessoal; " O formulário não é minimizado, podendo ser redimensionado com segurança ".
Cada frase pode ser reformulada dessa maneira (veja acima) e é a única maneira profissional de escrever.
fonte
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.
fonte
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 :)
fonte
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 :-)
fonte
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
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.
fonte
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
algum código desonesto, escrito com uma meia-boca, então descarte o comentário,passepor cima dele e dê um soco nocódigo confuso de um colega; então, fale com ele pessoalmente.fonte
CanThisFormBeResized
provavelmente deveria serThisFormCanBeResized
se vai ser usado assimIf ThisFormCanBeResized Then
.function() { return this.windowState != 1 }
sobre qualquer comentário. +1 de mimComo 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.
fonte
Pessoalmente, eu escreveria (em C #):
Ou algo nesse sentido, não precisando dos comentários.
fonte
ResizeWindowSafely
implicaria que pode ser chamado se você não souber se deve redimensionar ou não e, portanto, precisaria se incluirif (WindowState != WindowState.Minimised)
.