¿Los comentarios en primera persona distraen y no son profesionales?

Acabo de encontrarme escribiendo el siguiente comentario en algún código (arcaico de Visual Basic 6.0) que estaba escribiendo:

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

No estoy seguro de por qué inconscientemente uso "nosotros" en mis comentarios. Sospecho que es porque me imagino a alguien leyendo el código, como si realmente estuvieran "haciendo" todos los comandos en cada línea, en lugar de solo verlos suceder. Con esta mentalidad, podría haberlo usado I can resize it, ya que soy yo quien lo "hace" actualmente o you can resize it, como si estuviera hablando con quien lo "haga" en el futuro, pero dado que ambos casos probablemente sucede, yo uso "nosotros" como si estuviera guiando a otra persona a través de mi código.

Simplemente puedo reescribirlo it can be resizedy evitar el problema, pero ha despertado mi curiosidad: ¿es común usar a la primera persona como esta en los comentarios, o se considera que distrae y / o no es profesional?

Los comentarios deben ser escritos para que los seres humanos los entiendan. Cuando los seres humanos se comunican, generalmente usamos "yo", "nosotros", "usted", etc.

Cuando alguien intenta comprender algún código, hay dos o más actores: la persona que lo lee y el autor original del código. Decir "nosotros" está bien. A menos que sea "profesional", quiere decir "robot".

Sugeriría mantenerse alejado de usar 'I' porque automáticamente asume toda la responsabilidad del código. Si otras personas lo están leyendo, se vería mal porque está destinado a ser un esfuerzo de equipo en este caso. Soy indiferente sobre el uso de 'nosotros'. Sin embargo, puede parecer que incluye a otros lectores de manera no genuina.

Mi voto sigue siendo breve y conciso. Si el mensaje se puede transmitir de una manera menos detallada, ¿por qué elegir algo más? Entonces, con respecto a este ejemplo, escribiría:

'The form is not minimized so it can be resized safely.

Tomo uno de dos enfoques, generalmente lo que suena mejor.

Al explicar cosas como los requisitos o la justificación, voy con "nosotros" tal como lo tienes allí:

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

Si estoy explicando el proceso, tiendo a usar una voz imperativa (comando) (corríjame si ese es el término incorrecto):

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

Este último puede acercarse peligrosamente a repetir el código, pero hay usos. Por lo tanto, no está utilizando I o we, sino que en realidad implica "usted".

Creo que es solo una variación del estilo de escritura académico / técnico, que a menudo es impersonal. Usando la voz pasiva, usando el "real nosotros" ("uno" está muy anticuado).

Como regla general, no es específico quién lo usará de todos modos: el comentario es para beneficio de los mantenedores, no solo para el autor original.

Dicho esto, yo uso primera persona con bastante frecuencia en los comentarios - para explicar por qué he tomado decisiones particulares, y lo que yo estaba pensando.

Los comentarios deben decirle por qué se está haciendo algo, no qué se está haciendo. Si lo que se está haciendo no es obvio en el código, corríjalo, no solo agregue un comentario. La primera persona, la segunda persona, etc. no importan, lo que importa es comunicar la información necesaria.

Si debe narrar el código, prefiera los imperativos, p. Ej.

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

(Y no use constantes desnudas como "1" en el código)

¿Tal vez nos estamos refiriendo a los pequeños dentro del programa que hacen que la magia suceda? :)

La voz pasiva en inglés es difícil de usar y suena mal. A la gente le gusta usar formularios de persona (yo, tú, nosotros, uno).

Ejemplo:

(Usted / nosotros / uno debe) usar un delegado para pasar eventos de cambio de tamaño de ventana a padre

Se debe usar un delegado para pasar eventos de cambio de tamaño de ventana a padre

Otro ejemplo (tenga en cuenta que a menudo puede omitir los formularios de persona en los comentarios):

(Nosotros) atrapamos una excepción. (Estaremos) mostrando un diálogo de error.

Se detectó una excepción y se mostrará un cuadro de diálogo de error.

PD. Reemplazar el pasivo con "usted" es tan común en el idioma inglés que también comenzó a filtrarse a otros idiomas. Suena extremadamente divertido, por ejemplo, en finlandés, donde existe la segunda forma singular de la persona (como el inglés "you").

Si está hablando de la ejecución del programa, no se trata de "nosotros", "usted" o "yo". El antropomorfismo puede estar tan extendido como para pasar desapercibido, pero es un hábito peligroso (Advertencia de PDF. Advertencia de Dijkstra):

Creo que el antropomorfismo es lo peor de todo. Ahora he visto programas "tratando de hacer cosas", "queriendo hacer cosas", "creyendo que las cosas son verdaderas", "sabiendo cosas", etc. No seas tan ingenuo como para creer que este uso del lenguaje es inofensivo. Invita al programador a identificarse con la ejecución del programa y casi le impone el uso de la semántica operativa.

No creo que ni la primera persona ni el "real nosotros" parezcamos poco profesionales o que nos distraigan. Creo que deberíamos hacer un esfuerzo para escribir comentarios en inglés en E-Prime , el subconjunto de inglés que no posee el verbo "ser".

Si usa demasiado "to be" en los comentarios, obtendrá declaraciones confusas como:

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

Bueno, tal vez no todo de una vez, pero la cuestión de la igualdad realmente puede hacer que los comentarios no sean claros.

Creo que los requisitos de escritura en E-Prime ayudan a aclarar esos requisitos, ya que el escritor debe indicar un actor junto con la acción.

El estilo correcto para comentar es la tercera persona impersonal; " El formulario no está minimizado, por lo que puede redimensionarse de forma segura ".

• Soy ingenuo
• Eres grosero.
• Somos demasiado formales (y reales).

Cada oración se puede reformular de esta manera (ver arriba) y es la única forma profesional de escribir.

Depende del comentario.

Por lo general, escribo comentarios de la manera sugerida por The Mouth of a Cow . También siempre escribo comentarios generadores de documentación (Doxygen, JavaDoc) de esta manera.

Sin embargo, muchas veces descuidan el uso del control de versiones para identificar quién escribió / tocó líneas en los archivos fuente. Hay momentos en que decir "yo" es apropiado, especialmente cuando es bastante fácil rastrear el "yo" a la persona que escribió el código. Si usted, como individuo, tomó una decisión, le recomiendo usar "I" (junto con el control de versiones) para identificar y rastrear decisiones en línea con el código.

Mi buen padre (mhrip) preguntaba: "¿No tienes cosas más importantes con las que preocuparte?"

Sin embargo, personalmente, me gusta el "nosotros". Y también me pregunto por qué escribimos en documentos anteriores, ni siquiera en código, considerando que soy el único empleado en mi empresa.

Sin embargo, yo y yo estamos de acuerdo en que de esta manera nos sentimos menos solos :)

¿Soy el único que escribe "nosotros" y piensa "yo y la computadora" (o "mi equipo y la computadora")? "Nosotros" vamos a manejar la solicitud que nos dio el exterior, lo que significa que "necesitamos" leer la solicitud, abrir algunas ventanas, hacer algunos cálculos, en función de "nuestros" requisitos comerciales. Esto también ayuda a ver el código como parte de tu lado, no como el enemigo :-)

Para comentarios breves, a veces escribo en segunda persona, como si estuviera instruyendo a otra persona, casi como un mensaje dirigido al siguiente desarrollador para leer el comentario. Como

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

Comentarios más largos (como un encabezado de función largo o varias líneas de descripción del algoritmo) Trato de mantenerme neutral, sin primera persona, segunda persona o tercera persona.

Agregaste este comentario porque el código no era lo suficientemente claro. Generalmente encuentro que expresar la intención a través de métodos bien definidos evita el uso de comentarios. Por ejemplo, esa línea de podría haberse movido a un método llamado CanThisFormBeResized.

Un método bien nombrado, por pequeño que sea, supera un comentario, porque es fácil que los comentarios y el código no estén sincronizados.

Entonces, si la mayoría de los comentarios se pueden expresar en código, eso deja muy pocas razones para los comentarios

• Si su comentario es su opinión, comience con "I"
• Si cree que su comentario debería ser una opinión compartida (por ejemplo, una mejor práctica), comience con "nosotros"
• Si su comentario está dirigido a un código dudoso escrito por un poco ingenioso, deseche el comentario y camine y golpee el código confuso de un colega, luego diríjalo cara a cara con ellos.

Como regla general yo sugeriría utilizar la primera persona, es decir, I.

¿Por qué? No por la naturaleza posesiva del yo, sino porque cuando las personas hablan desde cualquier otra perspectiva, tienden a usar demasiadas palabras o hacen oraciones demasiado complejas, y se pierden al tratar de explicar las cosas. La primera persona tiende a ser siempre más fácil de leer.

Personalmente escribiría (en C #):

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

O algo por el estilo, por lo que no necesita los comentarios.