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

Los comentarios deben escribirse para que los seres humanos los entiendan. Cuando los seres humanos se comunican, usualmente usamos "I", "we", "you", etc.

Cuando alguien está tratando de comprender un 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 por "profesional", te refieras a "como un robot".

Le sugeriría que evite usar "I" porque asume automáticamente toda la responsabilidad del código. Si otras personas lo leen, se vería mal porque se supone que es un esfuerzo de equipo en este caso. Soy indiferente sobre el uso de 'nosotros'. Sin embargo, puede parecer que incluye a otros lectores de forma no genuina.

Mi voto todavía va por brevedad y concisión. Si el mensaje se puede transmitir de manera menos detallada, ¿por qué elegir otra cosa? Entonces, con respecto a este ejemplo, escribiría:

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

Tomo uno de los dos enfoques, generalmente cualquiera que suene mejor.

Al explicar cosas como los requisitos o la justificación, voy con "nosotros" como usted tiene:

// 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á usando yo ni nosotros, 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 "royal we" ("one" está tan anticuado).

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

Dicho esto, uso la primera persona con bastante frecuencia en los comentarios, para explicar por qué yo tomé decisiones particulares y qué pensaba yo .

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 importante es comunicar la información necesaria.

Si debe narrar el código, prefiera imperativos, por ejemplo,

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

(Y, por favor, no uses constantes simples como "1" en el código)

¿Quizás nosotros se refiere a los pequeños que están dentro del programa para hacer que suceda la magia? :)

El idioma inglés voz pasiva es difícil de usar y suena mal. A las personas les gusta usar formas personales (I, you, we, one).

Ejemplo:

  

(Usted / nosotros / uno debe) utiliza un delegado para pasar los eventos de cambio de tamaño de la ventana a los padres

     

Se debe usar un delegado para pasar los eventos de cambio de tamaño de la ventana a los padres

Otro ejemplo (tenga en cuenta que a menudo puede omitir los formularios de las personas 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.

PS. Reemplazar el pasivo por "usted" es tan común en el idioma inglés que también ha comenzado a filtrarse en otros idiomas. Suena extremadamente gracioso, por ejemplo, en finlandés, donde existe la segunda forma singular de la persona (como el inglés "tú").

Si estás hablando de la ejecución del programa, no es 'nosotros', 'tú' o 'yo'. El antropomorfismo puede estar tan extendido como para que no se note, pero es un hábito peligroso (Aviso PDF) Advertencia Dijkstra.):

  

Creo que el antropomorfismo es lo peor   todos. Ahora he visto programas "intentando   hacer cosas "," querer hacer cosas ",   "creyendo que las cosas son verdaderas",   "saber cosas" etc. no seas así   ingenuo como para creer que esto   El uso del lenguaje es inofensivo. Eso   invita al programador a identificar   él mismo con la ejecución del   Programa y casi lo obliga   El uso de la semántica operacional.

No creo que ni la primera persona ni el "real nosotros" parezcan poco profesionales o distraídos. 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 en exceso "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 todos a la vez, pero la igualdad de condiciones realmente puede hacer que los comentarios no estén claros.

Creo que los requisitos de escritura en E-Prime ayudan a aclarar esos requisitos, ya que el escritor debe indicar a 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 se puede cambiar el tamaño de forma segura ".

• I es ingenuo.
• Tú es burdo.
• Nosotros es demasiado formal (y real).

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 sugerido por la boca de una vaca . También siempre escribo comentarios que generan documentación (Doxygen, JavaDoc) de esta manera.

Sin embargo, muchas veces descuidan el uso del control de versiones para identificar quién escribió / tocó las líneas en los archivos de origen. Hay ocasiones en que es apropiado decir "yo", 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, recomiendo usar "I" (junto con el control de versiones) para identificar y rastrear las decisiones en línea con el código.

Mi buen padre (mhrip) preguntaría: "¿No tienes cosas más importantes para molestarse?"

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

Sin embargo, yo mismo 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, eso significa que "necesitamos" leer la solicitud, abrir algunas ventanas, hacer algunos cálculos, basados en "nuestros" requisitos comerciales. Esto también ayuda a ver el código como parte de tu lado, no del 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 que lea el comentario. Tales 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) Intento mantener neutral, en primera persona, en segunda persona o en 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 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 se desincronicen.

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 poco fiable escrito por un medio ingenio, luego deseche el comentario y camine y péguelo el código confuso de un colega, luego trate este tema cara a cara con ellos.

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

¿Por qué? No debido a la naturaleza posesiva de I, sino porque cuando las personas hablan desde cualquier otra perspectiva, tienden a usar demasiadas palabras o hacen que las oraciones sean demasiado complejas, y se pierden al tratar de explicar las cosas. La primera persona tiende a ser siempre la 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 comentarios.