visual tablas para lista leer insertar imagenes funciones datos codigos botones comments

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



insertar imagenes en r markdown (14)

Principalmente en voz pasiva, lo que generalmente es más importante que quién para mí.

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

etc.

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

Estos son comentarios, por ejemplo, de estilo escrito solamente, ¡no destinados a ser juzgados por su contenido! ...

  • Comentarios "I" en primera persona:

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

  • Comentarios de "nosotros" en primera persona:

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

  • 2da Persona:

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

  • 3era persona:

    //this needs to be set to one

"Yo", si es un truco, estoy avergonzado.

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

"Tú", si estoy explicando cómo usar una API.

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

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

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

Nunca se sabe si ese código se usará para otra persona, se puede vender el código, se puede publicar bajo licencia de código abierto, etc. Así que no es bueno ver "Estoy configurando esto ..." o "Necesitamos configurar esto ..." al menos, "Actualice las siguientes variables:"

Yo siempre uso la tercera persona y porque 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 uso para el código en sí mismo:

// verificar si el usuario ya tiene suscripción al boletín informativo

if (! mySubscription.Contains (myUser)) ...

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.

Usaré ''Yo'' si estoy explicando mi propia decisión de usar 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.

Uso principalmente el modo imperativo para frases únicas ("Calcule el foobar aplicando el algoritmo Barfoo", "Consulte Foo and Bar 1967 para obtener más detalles)," Nosotros "para obtener explicaciones más extensas que podrían ser extractos de un artículo técnico.

La tercera persona pasiva 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, así que esa es la guía que uso en mi documentación y comentarios.

Uso tercera persona para todos los comentarios.

//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

Prefiero la voz pasiva o imperativa (esta última solo para comentarios cortos) excepto cuando me refiero específicamente a mí mismo (primera persona del singular) (por ejemplo, una opinión o información no oficial que obtuve, por ejemplo, contactar al proveedor de una API mal documentada; o en una nota que documenta mi investigación de un conductor defectuoso (explicando una solución) o consultando mi correspondencia con un proveedor externo (con una referencia al correo electrónico en nuestro wiki) o a nuestra organización (primera persona en plural) (ej. cómo nuestra empresa usa el software, se implementa una referencia a una estrategia corporativa que tiene relación con algo).