Comentario antes o después de que el código en cuestión [cerrada]

Suponiendo un comentario no se ajusta (o no puede ir) en la línea que se aplica, debe uno escribir el comentario antes del código o después?

Bueno, donde los futuros lectores comprendan mejor el alcance del comentario. En otras palabras, donde la mayoría de los programadores / scripters ponen tales comentarios.

Entonces, ¿ dónde ponen un comentario la mayoría de los programadores / scripters: antes o después de su código?

Si su respuesta se aplica solo a idiomas específicos, indique cuál.

Y si puede citar una especificación o guía aceptada que respalde su respuesta, mucho mejor.

Yo comentaría en línea o antes del código al que debería aplicarse el comentario. El sentido de los comentarios es obtener una comprensión básica de lo que hace el código, sin la necesidad de leer el código en sí. Por lo tanto, tiene mucho más sentido colocar los comentarios antes del código que describe.

Microsoft dice que sería una buena práctica de programación comenzar los procedimientos con un pequeño comentario. (No mencionan comentarios después de los procedimientos) MSDN El enlace trata sobre VisualBasic pero creo que se aplica a la mayoría de los lenguajes de programación.

Prefiero que los comentarios estén por encima del código al que se refieren, simplemente tiene más sentido decirle a una persona que lee el código sobre lo que está por venir en lugar de tratar de referirse al código anterior para explicar que algunas líneas de código desordenadas solucionaron algún error que era complicado así que no lo toques.

Creo que el código generalmente se lee de arriba a abajo. Por lo menos, la memoria muscular me haría asociar un comentario con la siguiente línea de código debajo de él.

Por lo general, el comentario debe estar en la parte SUPERIOR de la fila después de la misma sangría que el trabajo. Por ejemplo, comentarios sobre el cuerpo de las funciones, y un comentario de línea justo arriba del comienzo de un algoritmo crítico.

La razón es que, cuando alguien comienza a leerlo, se hace evidente la pregunta de por qué se hace algo de esa manera; donde, como la persona no sabe hasta qué punto se necesita desplazarse para obtener la respuesta. Si está arriba, está ahí para ver.

Entonces, ¿dónde ponen un comentario la mayoría de los programadores / scripters: antes o después de su código?

En muchos años de programación usando una variedad de idiomas, no recuerdo haber visto ningún código en ningún idioma donde se coloque un comentario en una nueva línea después del código al que se refiere. En los EE. UU., Al menos, el estándar de facto está comentando antes del código o en la misma línea que sigue al código. Escribir sus comentarios después del código relacionado invita a una prueba de drogas, una evaluación psiquiátrica y / o una cita con un par de alicates y un soplete.

La única excepción que se me ocurre es un comentario que marca el final de una sección comentada anteriormente, como esta:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin escribió un ensayo bien considerado sobre comentarios que vale la pena leer. No dice si pone sus comentarios antes o después del código, pero sí dice que nunca los pone en línea, y apostaría mucho dinero a que tampoco los pone después.

Intenta comentar solo donde sea realmente necesario; el código debe intentar autodocumentarse siempre que sea posible.

Dicho esto, la ubicación puede depender: si usa una línea separada para el comentario, colóquela antes del código real. Si lo tiene en la misma línea, póngalo después.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Pero nunca:

int i = 0;
// this workaround is required to make the compiler happy

En realidad no soy un gran fanático de los comentarios. Durante un curso de ingeniería de software, me presentaron la idea del código autodocumentado. El código es la única documentación correcta 100% garantizada de sí mismo: los comentarios deben actualizarse, construirse cuidadosamente y ser relevantes, de lo contrario, son trampas que pueden ser peores que ningún comentario. No fue hasta que comencé a trabajar en una tienda de C ++ con una guía de estilo estricta y convenciones de nomenclatura significativas que realmente internalicé este concepto.

A veces los comentarios son necesarios. Muchas veces, la cuidadosa asignación de nombres a las variables, el uso significativo de espacios en blanco y la agrupación, y una organización lógica significativa del código en sí mismo eliminan la necesidad del comentario.

Esto realmente es una negación de la pretensión y la validez de su pregunta, en lugar de una respuesta a la pregunta que tenía. Todavía creo que es relevante y puede ayudarte, y no fui un imbécil. Si no, los -1 me dominarán.

Hacer que el comentario aparezca antes del código ayuda al lector a tener un contexto para el código que está a punto de encontrar. Mucho más humano que lanzarles el código y explicarles después de que ya están confundidos.

Bien, haré el caso "después": el código siempre debe ser la documentación principal, mientras que el comentario (que no tiene un significado semántico) es como una explicación entre paréntesis. Por lo tanto, si coloca el comentario debajo del código que necesita explicación, deja el código como la explicación principal y solo usa el comentario para aclararlo. Por ejemplo,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Si coloca el comentario antes de la prueba, el lector tenderá a leer el comentario como lo principal y es posible que no lea el código de cerca, sin darse cuenta de que se han equivocado:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Para tomar prestadas algunas ideas de la escritura técnica (al menos en el idioma inglés), cosas como notas y advertencias de precaución se colocan generalmente antes de la instrucción o sección a la que se aplica la nota o advertencia de advertencia.

No veo por qué el código no puede considerarse una forma de escritura técnica: cada bloque es una instrucción. Al igual que el idioma inglés, la mayoría de los lenguajes de programación se leen de izquierda a derecha, de arriba a abajo. Los comentarios son notas sobre el código: pueden identificar errores para corregir o cosas que un futuro desarrollador debe tener en cuenta.

Siguiendo esta relación, parece más apropiado poner el comentario sobre el bloque de código al que se refiere.

Es posible que un comentario deba ir arriba o debajo de un fragmento de código, según el tipo de comentario que sea: si proporciona una explicación ultra breve de lo que hace el código, entonces debe preceder al código; Si aclara detalladamente un detalle técnico sobre cómo funciona el código, entonces debe seguir el código.

Afortunadamente, un comentario puede ir arriba o debajo de un fragmento de código, y aún así no dejar dudas sobre a qué fragmento pertenece, haciendo un uso adecuado de las líneas en blanco. Por supuesto, los programadores que no prestan atención al uso de líneas en blanco no sabrán de lo que estoy hablando; Si usted es uno de esos, omita esta respuesta y continúe con su vida. Pero los programadores que prestan atención a las líneas en blanco saben muy bien que las líneas en blanco se usan para dividir el código en entidades lógicas. Entonces, si ves lo siguiente:

[blank line]
/* comment */
{ code }
[blank line]

Usted sabe que el comentario pertenece al código y que le dice qué hace el código. Mientras que, si ve lo siguiente:

[blank line]
{ code }
/* comment */
[blank line]

Una vez más, sabes muy bien que el comentario pertenece a ese código, y es una aclaración sobre cómo el código hace lo que hace.

Los comentarios anteriores son los mejores.

si tiene que incluir comentarios y su código no se explica por sí mismo, preferiría no confundirme con un bloque de código, entonces vea "ahh, eso es lo que se suponía que debía hacer".

El código puede (y debe) "auto documentarse", pero si tiene que leer y comprender cada línea de código para comprender cómo funciona un método. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Cuando me he regodeado sobre este tema, descubrí que la mayoría de los sistemas de documentación legibles por computadora (Doc XML, Doxygen, Java doc, etc.) esperan que el comentario llegue antes del código con el que se relaciona: es mejor seguir siendo compatible con ese estándar.

También estoy de acuerdo con el hilo SO: ¿deberíamos agregar comentarios después de los bloques de código, en lugar de antes? ..

También prefiero saber por adelantado ...

A menudo convierto los comentarios (tanto míos como escritos por otros) en declaraciones de registro de nivel de seguimiento. Esto generalmente hace que sea mucho más fácil entender dónde colocarlo.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Una ventaja adicional es que cuando las cosas se ponen difíciles puedo activar el rastreo de registros y obtener un registro de ejecución más detallado.