Acabei de encontrar 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" nos meus comentários. Eu suspeito que é porque eu imagino alguém percorrendo o código, como se eles estivessem realmente "fazendo" todos os comandos em cada linha, ao invés de apenas observá-los acontecerem. Com essa mentalidade, eu poderia ter usado I can resize it , já que eu sou o único "fazendo" atualmente, ou you can resize it , como se eu estivesse falando com quem está "fazendo" isso no futuro, mas já que ambos desses casos provavelmente acontecerão, eu uso "nós" como se eu estivesse liderando outra pessoa através do meu código.
Posso simplesmente reescrevê-lo como it can be resized e evitar o problema, mas despertou minha curiosidade: é comum usar a primeira pessoa assim nos comentários, ou é considerado distrativo e / ou não profissional?
Os comentários devem ser escritos para que os seres humanos entendam. 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. Dizendo "nós" está bem. A menos que seja por "profissional", você quer dizer "semelhante a um robô".
Sugiro ficar longe de usar 'eu' porque assume automaticamente toda a responsabilidade pelo código. Se outras pessoas estiverem lendo, ficaria ruim porque é um esforço de equipe nesse caso. Sou indiferente em usar 'nós'. Pode, no entanto, ser interpretado como incluindo outros leitores de forma não genuína.
O meu voto continua por concisão e concisão. Se a mensagem puder ser transmitida de maneira menos detalhada, por que escolher mais alguma coisa? Então, com relação a este exemplo, eu escreveria:
'The form is not minimized so it can be resized safely.
Eu tomo uma de duas abordagens, geralmente o que soa melhor.
Ao explicar coisas como requisitos ou justificativas, eu vou com "nós" como você tem aí:
// We can't proceed unless the user has given us this information.
Se eu estou explicando o processo, eu costumo usar uma voz imperativa (comando) (me corrija se esse é o termo errado):
// Get the foo from bar and make sure it follows our required format.
O último pode ficar perigosamente perto de repetir o código, mas existem usos. Então, não está usando eu ou nós, mas, na verdade, significa "você".
Eu acho que é apenas uma variação do estilo de escrita acadêmico / técnico, que é muitas vezes impessoal. Usando a voz passiva, usando o "royal we" ("um" é tão antiquado).
Como regra geral, é não específica, que irá usá-lo de qualquer maneira - o comentário é para o benefício dos mantenedores, normalmente não apenas para o autor original.
Dito isso, eu uso a primeira pessoa com bastante frequência nos comentários - para explicar por que eu tomei decisões específicas, e o que eu 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 apenas adicione um comentário. Primeira pessoa, segunda pessoa, etc. não importa, o que importa é comunicar a informação necessária.
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, por favor, não use constantes simples como "1" no código)
Talvez nós esteja se referindo aos pequeninos dentro do programa fazendo a mágica acontecer? :)
A voz passiva em inglês é difícil de usar e parece ruim. As pessoas gostam de usar formulários pessoais (eu, você, nós, um).
Exemplo:
(You/we/one must) use a delegate to pass window resize events to parent
A delegate has to be used for passing window resize events to parent
Outro exemplo (note que muitas vezes você pode omitir os formulários de pessoa nos comentários):
(We) caught an exception. (We'll be) showing an error dialog.
An exception was caught and an error dialog will be shown.
PS. A substituição de passivo por "você" é tão comum no idioma inglês que começou a vazar para outros idiomas também. Soa extremamente engraçado, por exemplo, em finlandês, onde existe a segunda pessoa do singular (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 difundido a ponto de ser imperceptível, mas é um hábito perigoso (PDF Advertência, p.ex. Aviso de Dijkstra.):
I think anthropomorphism is worst of all. I have now seen programs "trying to do things", "wanting to do things", "believing things to be true", "knowing things" etc. Don't be so naive as to believe that this use of language is harmless. It invites the programmer to identify himself with the execution of the program and almost forces upon him the use of operational semantics.
Eu não acho que nem a primeira pessoa nem o "real nós" pareçam não profissionais ou distrativos. Eu acho que devemos fazer um esforço para escrever comentários em inglês em E-Prime , o subconjunto do English que não possui o verbo "ser".
Se você usa demais "to be" nos comentários, recebe 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 não pode deixar os comentários claros.
Eu acho que escrever requisitos no E-Prime ajuda a tornar esses requisitos mais claros, já que 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 está minimizado, por isso pode ser redimensionado com segurança ".
Cada sentença pode ser reformulada dessa maneira (veja acima) e é a única maneira profissional de escrever.
Depende do comentário.
Geralmente, escrevo comentários da maneira sugerida sugerida pela boca de uma vaca . Eu 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 as 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 o "I" (juntamente com o controle de versão) para identificar e rastrear decisões em linha com o código.
Meu bom e velho pai (mhrip) perguntava: "Você não tem coisas mais importantes para se preocupar?"
No entanto, pessoalmente, gosto do "nós". E também me pergunto por que escrevo nós em documentos a montante, nem mesmo em código, considerando que sou o único funcionário da minha empresa.
No entanto, eu e eu concordamos que desta forma 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 o pedido que o exterior nos deu, o que significa "nós" precisamos ler o pedido, abrir algumas janelas, fazer alguns cálculos, com base em "nossos" requisitos de negócios. Isso também ajuda a ver o código como parte do seu lado, não o inimigo: -)
Para breves comentários, às vezes escrevo na segunda pessoa, como se estivesse instruindo outra pessoa, quase como uma mensagem direcionada ao próximo desenvolvedor a ler o comentário. 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-me neutro, sem primeira pessoa, segunda pessoa ou terceira pessoa.
Você adicionou este comentário porque o código não estava claro o suficiente. Eu geralmente acho que expressar intenção através de métodos bem definidos evita o uso de comentários. Por exemplo, essa linha poderia ter sido movida para um método chamado CanThisFormBeResized .
Um método bem conhecido, por menor que seja, bate um comentário, porque é fácil para os comentários e o código ficarem fora de sincronia.
Assim, se a maioria dos comentários pode ser expressa em código, isso deixa muito poucos motivos para comentários
Como regra geral, sugiro usar a primeira pessoa, ou seja, I .
Por quê? Não por causa da natureza possessiva do 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 tentando 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, portanto, dos comentários.
Tags coding-standards comments