¿Qué estilo de escritura usas para comentar el código?

Question

Realmente tengo curiosidad, pero si alguien quiere argumentar que uno es mejor que otro, ¡adelante!

Estos son comentarios para ejemplo de estilo de escritura única, no susceptible de ser apreciada por su contenido ....

• primera persona "I" comentarios:

  //i'm setting this to 1 because it breaks otherwise 
  

• Primeros persona "nosotros" comentarios:

  //we need to set this to 1 - trust me 
  

• segunda persona:

  //you need to set this to 1 so it don't break 
  

• tercera persona:

  //this needs to be set to one 
  

Answer 1

"I", si es un truco por el que estoy avergonzado.

"Nosotros", si estoy llevando al lector a través de un algoritmo confuso.

"Usted", si le explico cómo usar una API.

Answer 2

Aquí hay un enlace de Microsoft, que está dirigido específicamente a la codificación de las normas/pautas al que apuntan a la plataforma .NET. Pero podría ser útil.

http://msdn.microsoft.com/en-us/library/aa291593.aspx#vxconcodingtechniquesanchor2

Y de su opción de 4, que tienden a utilizar # 4.

Answer 3

Mezclo los tres según corresponda, lo que podría no ser la mejor práctica al componer en prosa.

Answer 4

Voy a alternar entre "I" y "nosotros" dependiendo de si es totalmente mi culpa, o una decisión de programación de un comité/compañero.

Answer 5

voy a utilizar 'yo' si yo estoy explicando mi propia decisión de utilizar una cierta lógica o patrón. Si se trata de un proyecto grupal, generalmente firmaré ese comentario para que la gente pueda acudir a mí directamente con preguntas.

De lo contrario, usaré tercera persona.

Answer 6

Uso tercera persona para todos los comentarios.

Answer 7

nunca se sabe si ese código será utilizado para otra persona, puede vender el código, puede publicada bajo cualquier licencia de código abierto, etc ... lo que no es bueno para ver "Soy la creación de este. .. "o" Necesitamos configurar esto ..."Por lo menos, 'Por favor, actualice las siguientes variables:'

siempre uso la tercera persona y haré lo eres, siempre uso

/********************************************* 
** 
** last edited by Bruno Alexandre, 14.Oct.08 
** log info: 
** - 10.Oct.08 : Added send email when buggy 
** 
************************************************/ 

en la parte superior de cada página de códigos (clases, CSS, Javascript, etc)

y utilizar al mismo código que: (! mySubscription.Contains (myUser)

// comprobar si el usuario ya tiene boletín de suscripción

si) ...

Answer 8

Tercera persona, pero, por favor, incluya una explicación. No es necesario que sea largo o exhaustivo, solo por qué está haciendo esto, qué se romperá si se cambia, algo. No, no confío en ti, o no confío en que las circunstancias actuales siempre requieran este truco. El error asociado podría arreglarse ahora, cinco años después. O podría ser más fácil de arreglar.

Answer 9

Depersonalizo mis comentarios o uso "nosotros". "Nosotros" en el sentido de caminar a través del algoritmo con el lector.

Answer 10

Principalmente uso el modo imperativo para frases sueltas ("Calcule el foobar aplicando el algoritmo barfoo", "Refiérase a Foo and Bar 1967 para más detalles)," Nosotros "para explicaciones más largas que podrían ser extractos de un documento técnico artículo

pasivo tercera persona es más tradicional, pero muchas revistas científicas prefieren el "nosotros" más activo, ya que es más legible. También es mi forma favorita, esa es la guía que uso en mi documentación y comentarios

Answer 11

//use imperative mode, few person/reader references if any 
//comments generally annotate the code, rarely talk to the reader 
//there is no reason to talk to the reader 
//this is not a primer or a tutorial 
//just record the information 
//state the context 
//note the exceptional cases 
//justify the choices 
//list just the facts 
//save the prose for poetry and sci-fi 
//some code is sci-fi, but hopefully not this 

Answer 12

Principalmente en voz pasiva, qué es general Es más importante que que para mí.

//This must be set to one for configuration 
// This is yet to be implemented 
// still to be evaluated for edge cases 

etc.

Answer 13

prefiero la voz pasiva o imperativo (este último sólo para comentarios cortos) excepto cuando me refiero específicamente a mí mismo (primera persona del singular) (por ejemplo, una opinión o que la información no oficial que Obtuve, por ejemplo, contactando al proveedor de una API mal documentada, o en una nota que documentaba mi investigación de un controlador defectuoso (explicando una solución) o consultando mi correspondencia con un proveedor externo (con una referencia al correo electrónico en nuestra wiki))) o para nuestra organización (primera persona plural) (por ejemplo, cómo nuestra empresa utiliza el software, se implementa una referencia a una estrategia corporativa que tiene relación con algo).

Answer 14

Siempre me ha gustado esta guía de estilo de Sun/Oracle, independientemente del lenguaje de programación: How to Write Doc Comments for the Javadoc Tool: Style Guide. Las reglas mantienen las cosas formales y consistentes sin hacer el ridículo: creo que Orwell aprobaría