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

34

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.

comments

— msh210
fuente

3

Considera lo que sucede cuando lo pones después. El programador leyó el código. Decirse a sí mismo WTF esto está haciendo? Ver el comentario Lee el código nuevamente. En algún momento lo entiendo o te rindas. Así que sé amable y evita la parte 1 y 2 poniéndola encima.

— deadalnix

@deadalnix, gracias, esa parece ser la esencia de la respuesta de Dipan Mehta también. (Gracias también a todos los que respondieron hasta ahora, y +1 a cada uno.)

— msh210

22

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.

— dasheddot
fuente

1

Marque, ya que esta es la única respuesta (hasta ahora) que responde claramente a la pregunta, que no buscaba preferencias personales sino un procedimiento operativo estándar, en el sentido de que cita MSDN.

— msh210

1

@ msh210: ¿Entonces prefiere una preferencia de Microsoft a las preferencias personales de otros buenos programadores? ¿PERO SABES cómo Microsoft entendió mal la notación húngara como estándar? ¿Sí? ¿Vos si? Solo confíe en el sentido común, no siempre corra con la horda o siga al toro más grande.

— Falcon

2

@Falcon, nunca he oído hablar de la notación húngara, y sospecho que la preferencia de MSDN fue al menos el resultado de un montón de comentarios de los empleados de MS; Las respuestas aquí, por el contrario, son de autoría individual.

— msh210

43

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.

— Ryathal
fuente

9

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.

— Joshua Smith
fuente

7

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.

— Dipan Mehta
fuente

6

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.

— Caleb
fuente

4

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

— Lucero
fuente

Vuelva a leer la pregunta: especifica que está preguntando sobre un comentario en una línea separada.

— msh210

2

@ msh210 Esta es una respuesta perfecta. "escribe comentarios antes". Es aún más detallado y da una posible razón por la que podría pensar que están después de "Excepto cuando son cortos y están al final de la línea".

— rds

3

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.

— Brian Stinar
fuente

10

El código autodocumentado puede responder "qué" y "cómo", pero no importa cuán bien escrito, el código por sí solo rara vez puede responder la pregunta "¿Por qué?". Si hay un documento de requisitos completo, a veces puede encontrar la respuesta allí. De lo contrario, los comentarios son a menudo todo lo que tiene que explicar por qué el código debe hacer lo que hace.

— Ed Staub

1

No estoy de acuerdo Como dice @EdStaub, comentando responde una pregunta diferente, a un nivel diferente. Además, el código no es necesariamente de código abierto. E incluso cuando es así, no quiero leer un código fuente de marco para saber cómo usarlo.

— rds

44

Obviamente, nunca se ha ocupado del hardware (o de la interacción con un software mal escrito). Recientemente terminé de escribir una clase especializada para hablar con un controlador de motor bastante oscuro (y malhumorado ). Tiene todo tipo de requisitos extraños para la interfaz. A menos que tenga literalmente una función por línea, no hay forma de hacer que el código sea comprensible sin comentarios.

— Nombre falso el

3

@Brian, las preguntas "Por qué" a menudo son muy específicas, por ejemplo, evitar errores en una API y / o explicar que algo que parece incorrecto es realmente correcto. Esos son solo un par de ejemplos. No quisiera que los comentarios sean un documento completo de requisitos. Pero tampoco trataría de explicar la justificación de cada pequeño detalle de implementación en una especificación de requisitos (o incluso una especificación de diseño).

— Ed Staub

1

@codesparkle: estoy de acuerdo en que los comentarios utilizados como excusa para evitar la refactorización son generalmente malos. Sin embargo, esto no significa que todos los comentarios sean malos, solo que los comentarios abusados de esa manera lo son. El hecho es que hay una serie de situaciones en las que los comentarios son realmente la mejor opción para aclarar requisitos de codificación extraños.

— Nombre falso

2

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.

— Dan Ray
fuente

2

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){ ... }

— Larry OBrien
fuente

55

Ambos bloques de código tienen comentarios antes del código que están comentando.

— msh210

sus propios comentarios negaron su "después del caso" jeje :) abrazos y +1 por hacerlo un ejemplo temático navideño

— Ahmed Masud

1

@ msh210 Veo mis comentarios en el primer ejemplo como comentarios en la prueba if (navidad), no como "sobre" las siguientes funciones (es decir, están diciendo "¿qué significa que estamos aquí?") Preceden un bloque de código, pero nunca he visto código que tuviera ... code (); código(); / * comentario que explica el bloque anterior * /} y no tomó la pregunta de esa manera

— Larry OBrien

1

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.

— Thomas Owens
fuente

1

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.

— Mike Nakis
fuente

Como siempre digo: tu voto negativo sin una explicación no me ayuda a ser una mejor persona. ¡También te amo!

— Mike Nakis

1

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

— Niranjan Singh
fuente

1

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.

— mosquito
fuente