comments - significa - ¿Cómo te gustan tus comentarios?
flipo significado (9)
¿Cuáles son sus mejores prácticas para comentarios? ¿Cuándo deberían usarse y qué deberían contener? O los comentarios son necesarios?
Creo que depende del escenario.
Los métodos / funciones / clases necesitan una breve descripción de lo que hacen, cómo lo hacen, lo que toman y lo que devuelven, si no es inmediatamente obvio y que generalmente (en mi código) viene en la forma de un bloque de comentarios estilo javadoc .
En el código del bloque, tiendo a dejar un comentario sobre un bloque de líneas para explicar lo que hace, o uno al final de la línea si se trata de una llamada de función corta y críptica.
En la escuela, la regla era comentar todo, tanto que los comentarios superan al código. Creo que eso es tonto.
Creo que los comentarios deberían usarse para documentar el código "por qué" detrás del código, no el "cómo" ... el código mismo explica el "cómo". Si hay una operación que no es muy clara en cuanto a por qué se hace, ese es un buen lugar para hacer un comentario.
TODO y FIXME a veces van en comentarios, pero idealmente deberían ir en la administración de código fuente y las herramientas de seguimiento de errores.
La única excepción de donde no me preocupan los comentarios aparentemente inútiles es para los generadores de documentación, que solo imprimirán la documentación de las funciones que se comentan; en ese caso, todas las clases públicas y la interfaz API deben comentarse al menos lo suficiente para obtener la documentación generado.
Idealmente, su programa puede comunicarse con el lector en código y no en comentarios. La capacidad de escribir software que otros programadores puedan entender rápidamente separa a los mejores programadores del promedio en mi opinión. Normalmente, si usted o sus colegas no pueden entender una sección de código sin comentarios, entonces esto es un "olor a código" y la refactorización debería estar en orden. Sin embargo, habrá algunas bibliotecas arcaicas u otra integración que algunos comentarios para guiar al desarrollador promedio no son necesariamente malas.
Los comentarios son esenciales para la mantenibilidad. El punto más importante para recordar es explicar POR QUÉ estás haciendo algo, no QUÉ estás haciendo.
Creo que el nuevo movimiento para eliminar comentarios es malo ... la razón es que hay muchos programadores que piensan que están escribiendo un código fácil de entender que no necesita comentarios. Pero en realidad simplemente no es el caso.
¿Qué porcentaje del código de otras personas lees y entiendes al instante? Tal vez leo demasiado ASP clásico, Perl y C ++, pero la mayoría de las cosas que leo son difíciles de leer.
¿Alguna vez leíste el código de alguien y te confundiste por completo con él? ¿Crees que pensaron mientras escriben? Esto es una mierda, pero realmente no me importa. Probablemente pensaron ohh ... esto es muy inteligente y será SUPER rápido.
Como a menudo la respuesta es: depende. Creo que la razón por la que escribió un comentario es muy importante para la decisión, si el comentario es bueno o malo. Hay varios motivos posibles para los comentarios:
- para hacer la estructura más clara (es decir, qué ciclo terminó aquí)
Malo: parece un posible olor a código. ¿Por qué el código es tan complicado, que necesita un comentario para aclararlo?
- para explicar, lo que hace el código
Muy malo: Esto es en mi opinión peligroso. A menudo sucederá que más tarde cambie el código y se olvide del comentario. Ahora el comentario es incorrecto Esto es muy malo.
- para indicar una solución provisional / una corrección de errores
Bueno: a veces la solución a un problema parece clara, pero el enfoque simple tiene un problema. Si soluciona el problema, puede ser útil agregar un comentario, por qué se eligió este enfoque. De lo contrario, otro programador más tarde puede pensar que "optimiza" el código y reintroduce el error. Piensa en el problema Debian OpenSSL. Los desarrolladores de Debian eliminaron una variable unitaria. Normalmente, una variable unitaria es un problema, en este caso fue necesaria para la aleatoriedad. Un comentario del código habría ayudado a aclarar eso.
- para fines de documentación
Bueno: se puede generar cierta documentación a partir de comentarios formateados especiales (es decir, Javadoc). Es útil documentar las API públicas, que es imprescindible. Es importante recordar que la documentación contiene la intención del código, no la implementación. Entonces, responde al comentario la pregunta ''¿Por qué necesita el método (y cómo lo usa)'' o qué significa el método?
Echa un vistazo a Code Complete . Es simplemente lo mejor para tales temas.
Solo algunos comentarios:
Los comentarios son importantes para todo lo que no se puede inferir fácilmente del código (por ejemplo, algoritmos matemáticos complejos).
Los problemas con los comentarios es que deben mantenerse como el código, pero a menudo no se mantienen.
No me gustan los comentarios como este:
// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
Mejor:
CreateAnalyzeButton();
void CreateAnalyzeButton()
{
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
}
Ahora el código cuenta la historia completa. No es necesario un comentario.
Utilice la búsqueda de etiquetas y verá que SO ya tiene un montón de discusiones sobre los comentarios del código:
https://.com/questions/tagged/comments