Buenos casos de uso de comentarios

Question

Siempre he odiado los comentarios que llenan la mitad de la pantalla con asteriscos solo para decirte que la función devuelve una cadena, nunca he leído esos comentarios.

Sin embargo, leo comentarios que describen por qué se hace algo y cómo se hace (generalmente los comentarios de una sola línea en el código); estos son realmente útiles cuando se trata de entender el código de otra persona.

Pero cuando se trata de escribir comentarios, no escribo eso, sino que utilizo comentarios solo cuando escribo algoritmos en concursos de programación, pienso en cómo el algoritmo hará lo que hace y luego escribiría cada uno en un comentario, luego escribe el código que corresponde a ese comentario.

Un ejemplo sería:

//loop though all the names from n to j - 1 

Aparte de eso no puedo imaginar por qué alguien podría perder un tiempo valioso escribir comentarios cuando podría estar escribiendo código.

¿Estoy bien o mal? ¿Me estoy perdiendo de algo? ¿Qué otros buenos casos de uso de comentarios no conozco?

Answer 1

Si usa algo como Doxygen, puede documentar completamente sus tipos de devolución, argumentos, etc. y generar un buen "manual de código fuente". A menudo hago esto por los clientes para que el equipo que hereda mi código no se pierda del todo (o se vea obligado a revisar cada encabezado).

Los bloques de documentación a menudo se exageran, especialmente los lenguajes fuertemente tipados. Tiene mucho más sentido ser detallado con algo como Python o PHP que C++ o Java. Dicho esto, todavía es bueno hacer para los miembros & miembros que no se explican por sí mismos (actualización no nombrada, por ejemplo).

Me han ahorrado muchas horas de pensamiento, simplemente comentando lo que me gustaría decir a mí mismo si estuviera leyendo mi código por primera vez. Más narrativa y menos observación. Los comentarios no solo deberían ayudar a otros, sino también al ... especialmente si no lo ha tocado en cinco años. Tengo un Perl de diez años que escribí y todavía no sé qué es lo que hace.

Algo muy sucio, que he hecho en PHP & Python, es usar reflexión para recuperar bloques de comentarios y elementos de etiquetas en la interfaz de usuario. Es un caso de uso, aunque desagradable.

Si utilizo un rastreador de errores, también dejaré caer el ID del error cerca de mis cambios, de modo que tenga una referencia de regreso al rastreador. Esto es además de una breve descripción del cambio (registros de cambios en línea).

También violo la regla de "solo comentar por qué no qué" cuando estoy haciendo algo que mis colegas rara vez ven ... o cuando la sutileza es importante. Por ejemplo:

for (int i = 50; i--;) cout << i; // looping from 49..0 in reverse 
for (int i = 50; --i;) cout << i; // looping from 49..1 in reverse 

Answer 2

Los comentarios deben expresar qué que está haciendo algo que no es lo que está haciendo

Answer 3

Es un viejo dicho, pero una buena métrica a utilizar es:

comentario qué que estás haciendo algo, no cómo lo estás haciendo.

Diciendo "recorrer todos los nombres de n a j-1" debe ser inmediatamente claro incluso para un programador novato solo desde el código. Dar la razón por la que estás haciendo eso puede ayudar con la legibilidad.

Answer 4

No es una mala idea para grabar lo que piensa su código debe ser la plena (especialmente si el código no es intuitiva, si desea mantener los comentarios a un mínimo), de modo que alguien que lea una fecha posterior, tiene un tiempo más fácil cuando se depura/corrección de errores. Aunque una de las cosas más frustrantes para encontrar en la lectura del código de otra persona es casos donde el código ha sido actualizado, pero no los comentarios ....

Answer 5

Siempre he odiado los comentarios que llenan la mitad de la pantalla con asteriscos simplemente a decir que la función devuelve una cadena, Nunca leo los comentarios.

Algunos comentarios en ese orden de ideas, no por lo general con el formato que extrema, existe realmente para ayudar a herramientas como Doxygen JavaDoc y generar documentación de su código. Esto, creo, es una buena forma de comentario, ya que tiene un formato legible tanto humano como máquina para la documentación (para que la máquina pueda traducirlo a otros formatos más útiles, como HTML), acerca la documentación al código. que documenta (de modo que si el código cambia, la documentación es más probable que se actualice para reflejar estos cambios), y generalmente da una buena (e inmediata) explicación a alguien nuevo en una gran base de código de por qué existe una función en particular.

De lo contrario, estoy de acuerdo con todo lo demás que se ha dicho. Comenta por qué, y solo comenta cuando no sea obvio. Aparte de los comentarios de Doxygen, mi código generalmente tiene muy pocos comentarios.

Answer 6

Comenta todo lo que piensas que no es sencillo y no podrás comprender la próxima vez que veas tu código.

Answer 7

Otro tipo de comentario que es generalmente inútil es:

// Commented out by Lumpy Cheetosian on 1/17/2009 

... uh, OK, el sistema de control de código fuente que me habría dicho. Lo que no me dirá es POR QUÉ Lumpy comentó esta pieza de código aparentemente necesaria. Dado que Lumpy está ubicado en Elbonia, no podré averiguarlo hasta el lunes cuando todos regresen del festival de vacaciones de Snerkrumph.

Considere a su audiencia y mantenga el nivel de ruido bajo. Si sus comentarios incluyen demasiada basura irrelevante, los desarrolladores simplemente los ignorarán en la práctica.

Por cierto: (. O Doxygen, o equivalentes) Javadoc es una buena cosa (TM), en mi humilde opinión.

Answer 8

También uso comentarios para documentar de dónde proviene un requisito específico. De esta forma, el desarrollador puede ver más adelante el requisito que hizo que el código sea como era y, si el nuevo requisito entra en conflicto con el otro requerimiento, se resuelve antes de romper un proceso existente. Donde trabajo, los requisitos pueden provenir de diferentes grupos de personas que pueden no conocer otros requisitos que el sistema debe cumplir. También nos preguntan con frecuencia por qué estamos haciendo cierta cosa de una determinada manera para un cliente en particular y nos ayuda a poder investigar para saber qué solicitudes en nuestro sistema de seguimiento causaron que el código sea como es. Esto también se puede hacer al guardar el código en el sistema de control de fuente, pero considero que esas notas también son comentarios.

Answer 9

utilizan los comentarios en las siguientes situaciones:

1. de alto nivel de documentación API de comentarios, es decir, lo que se esta clase o función para?
2. Comentando el "por qué".
3. Resumen breve y de alto nivel de lo que hace un bloque de código mucho más largo. La palabra clave aquí es resumen. Si alguien quiere más detalles, el código debe ser lo suficientemente claro como para que pueda obtenerlo del código. El objetivo aquí es facilitar que alguien que navegue por el código descubra dónde está la lógica sin tener que pasar por los detalles de cómo se realiza. Idealmente, estos casos deberían tenerse en cuenta en funciones separadas, pero a veces simplemente no es factible porque la función tendría 15 parámetros y/o no sería identificable.
4. Señalando sutilezas que son visibles por leer el código si realmente está prestando atención, pero no se destacan tanto como deberían debido a su importancia.
5. Cuando tengo una buena razón por la que necesito para hacer algo de una manera hackish (rendimiento, etc.) y no puedo escribir el código más claramente en lugar de usar un comentario.

Answer 10

Me recuerda a

Real programmers don't write documentation

Answer 11

de escribir este comentario hace un tiempo, y me ha ahorrado horas desde:

// NOTE: the close-bracket above is NOT the class Items. 
// There are multiple classes in this file. 
// I've already wasted lots of time wondering, 
// "why does this new method I added at the end of the class not exist?".