¿Te gustan tus comentarios?[cerrado]

StackOverflow https://stackoverflow.com/questions/121945

  •  02-07-2019
  •  | 
  •  

Pregunta

¿Cuáles son sus mejores prácticas para los comentarios?¿Cuándo deben utilizarse y qué deben contener?¿O incluso se necesitan comentarios?

¿Fue útil?

Solución

Los comentarios son esenciales para el mantenimiento.El punto más importante a recordar es explicar POR QUÉ estás haciendo algo, no QUÉ Tú lo estás haciendo.

Otros consejos

En la escuela, la regla era comentar todo, hasta el punto de que los comentarios pesan más que el código.Creo que eso es una tontería.

Creo que los comentarios deberían usarse para documentar el "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 está muy clara en cuanto a por qué se realiza, ese es un buen lugar para hacer un comentario.

Los TODO y FIXME a veces van en los comentarios, pero idealmente deberían ir en las herramientas de gestión de código fuente y seguimiento de errores.

La única excepción en la que no me importan los comentarios aparentemente inútiles es para los generadores de documentación, que solo imprimirán documentación para las funciones comentadas; en ese caso, cada clase pública e interfaz API deben comentarse al menos lo suficiente para obtener la documentación. generado.

Idealmente, su programa puede comunicarse con el lector mediante código y no mediante comentarios.En mi opinión, la capacidad de escribir software que otros programadores puedan comprender rápidamente separa a los mejores programadores del promedio.Normalmente, si usted o sus colegas no pueden entender una sección de código sin comentarios, entonces se trata de un "olor a código" y la refactorización debería ser necesaria.Sin embargo, habrá algunas bibliotecas arcaicas u otras integraciones que algunos comentarios para guiar al desarrollador promedio no son necesariamente malos.

Como suele ocurrir, la respuesta es:Eso depende.Creo que la razón por la que escribiste un comentario es muy importante para la decisión, si el comentario es bueno o malo.Hay varias razones posibles para los comentarios:

  • para hacer la estructura más clara (es decir,qué bucle terminó aquí)

Malo: Esto parece un posible olor a código.¿Por qué el código es tan complicado que necesita un comentario para aclararlo?

  • para explicar qué hace el código

Muy mal: En mi opinión, esto es peligroso.A menudo sucederá que luego cambies el código y te olvides del comentario.Ahora el comentario está mal.Esto es muy malo.

  • para indicar una solución alternativa/una corrección de errores

Bien: A veces la solución a un problema parece clara, pero el enfoque simple tiene un problema.Si soluciona el problema, puede resultar útil agregar un comentario explicando por qué se eligió este enfoque.De lo contrario, otro programador podría pensar más tarde que "optimiza" el código y reintroduce el error.Piense en el problema de Debian OpenSSL.Los desarrolladores de Debian eliminaron una variable unificada.Normalmente una variable unitaria es un problema; en este caso era necesaria por aleatoriedad.Un comentario de código habría ayudado a aclarar eso.

  • para fines de documentación

Bien: Parte de la documentación se puede generar a partir de comentarios con formato especial (es decir,Javadoc).Es útil documentar las API públicas, algo 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é necesitas el método (y cómo lo usas)' o ¿Qué significa el método?

Creo que el nuevo movimiento para eliminar comentarios es malo...La razón es que hay muchos programadores que piensan que están escribiendo 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 lo entiendes instantáneamente?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 has leído el código de alguien y te has sentido completamente confundido?¿Crees que pensaron mientras escribían? Esto es una mierda, pero realmente no me importa.Probablemente pensaron ohh...esto es muy inteligente y lo será SÚPER rápido.

Sólo algunas observaciones:

Los comentarios son importantes para todo lo que no se puede inferir fácilmente del código (p. ej.algoritmos matemáticos complejos).

El problema con los comentarios es que deben mantenerse como el código, pero a menudo no se mantienen en absoluto.

No me gustan 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 toda la historia.No es necesario un comentario.

Creo que depende del escenario.

Los métodos/funciones/clases necesitan una breve descripción de lo que hacen, cómo lo hacen, qué toman y qué devuelven, si no es inmediatamente obvio y eso generalmente (en mi código) viene en forma de un bloque de comentarios estilo javadoc. .

Código en bloque, tiendo a dejar un comentario encima de 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 breve y críptica.

Utilice la búsqueda de etiquetas y encontrará que SO ya tiene mucha discusión sobre los comentarios de código:

https://stackoverflow.com/questions/tagged/comments

Comentar código

Mira esto Código completo.Es simplemente mejor para esos temas.

Licenciado bajo: CC-BY-SA con atribución
No afiliado a StackOverflow
scroll top