¿Cuál es la proporción código de oro/comentario?[cerrado]

https://stackoverflow.com/questions/111563

02-07-2019
|

Pregunta

¿Existe una relación código/comentario que considere un signo de buena (mala) salud del código?

¿Puede darnos ejemplos de proyectos de código abierto que se consideren bien codificados y su respectiva proporción de comentarios?

(Me doy cuenta de que ninguna proporción es "verdadera" para todos los proyectos y es muy posible que haya proyectos de mala calidad que exhiban esta teórica proporción áurea.Aún...)

Solución

Los comentarios deben ser muy raros y valiosos, casi siempre expresando el "por qué" y nunca el "cómo" (la excepción es cuando el cómo es complejo y no se puede discernir fácilmente en el código).

Cada comentario es una pista de que es posible que deba refactorizar para aclarar la intención del código.Cada comentario corre el riesgo de quedar obsoleto tan pronto como se escribe.

Casi no tenemos comentarios aparte de los comentarios XML en nuestro proyecto xUnit.net, pero algunas personas Parece que el código es claro y fácil de leer.:)

Otros consejos

Quien tenga que arreglar código de otro programador dirá tantos comentarios como sea posible.El gran problema con el código antiguo es:"Ves lo que hace el código.Ya ves que este es el problema.Pero no sabes por qué el programador lo escribió así."

Para entender un error necesitas saber:

qué debería el código lo hace (no qué el código lo hace) y por qué.
El contrato de cada función.Por ejemplo, si hay una NullPointerException, ¿dónde está el error?¿En la función o en la función que llama?
En cada Hack se describe cómo se puede reproducir el problema (versión de idioma, sistema operativo, versión del sistema operativo).Por ejemplo, tenemos muchos trucos para una máquina virtual Java antigua que ya no es compatible.Pero no estamos seguros de poder eliminarlo porque no sabemos cómo reproducirlos.

Tenemos una proporción del 2-3%, que es muy poca.Creo que el 10% es bueno para proyectos grandes o de larga duración.

Lo sentimos, no existe una regla general.Los marcos y las bibliotecas, por ejemplo, requieren muchos más comentarios porque los programadores serán clientes y no tendrán tiempo para leer el código cada vez que necesiten invocar un método.

Los proyectos en los que escribe/lee código necesitan menos comentarios y deben intentar mejorar la legibilidad del código en lugar de la proporción comentario/código.

Atentamente

Los comentarios no sólo explican el código, sino que también guían al depurador que busca el fragmento de código que hace algo.

Recuperar el historial de pedidos de un cliente o calcular si un jugador enemigo es visible puede requerir decenas de líneas de código, e incluso un programador experto puede tardar varios minutos en estar seguro de que eso es lo que hace.Un comentario que dice "recuperar el historial de pedidos del cliente" permite que el depurador no investigue ese código en absoluto, si sabe que el historial de pedidos no es el problema.

Comento todo lo que creo que es ambiguo, o debería explicarse.A menudo, comento demasiado.¿Por qué?Porque nunca se sabe quién trabajará en su código.Me gusta imaginar una situación en la que reemplazan a la mitad del equipo con monos que solo entienden que cuando presionan enter en una línea, obtienen un plátano.Entonces, si al menos aprenden a leer, no cambiarán mi lógica sin leer primero los comentarios.

Caso y punto:

// Delete the helloworld file
exec("rm -f helloworld.txt")

No se cambiará a:

exec("rm -rf /")

Es poco probable, lo sé, pero incluso algunos bien Se sabe que los desarrolladores cambian la lógica porque no se ve bien y no porque hubo un error o un cambio de requisito.

Creo que todos pueden estar de acuerdo en que 0 comentarios generalmente pueden considerarse código subdocumentado.Recuerde que incluso el código más autodocumentado sólo puede documentar lo que allá;nunca lo que se omitió intencionalmente, se optimizó, se probó y se descartó, etc.Siempre necesitarás algo de inglés, básicamente, en tus archivos fuente, o seguramente omitirás importantes advertencias y decisiones de diseño.

Estoy interesado en cómo estos sólidos principios que ustedes defienden (con los cuales estoy totalmente de acuerdo hasta ahora) se traducen en estadísticas de código.En particular, qué proyectos de código abierto se consideran bien (no demasiado) documentados y cuál es la proporción de comentarios allí.

Tengo una regla general muy simple:Si necesita detenerse y pensar más de ~15 segundos al codificar algún fragmento de código (por ejemplo, una función o un bucle complejo, etc.), entonces ese fragmento de código necesita un comentario.

Funciona muy bien para mí.La próxima vez que usted, o alguien con su nivel de comprensión del código base general, se encuentre con ese fragmento de código, lo verá inmediatamente. por qué ¿Se hizo como se hizo?

LOC / LOcomment = yearsofexp / 5

Mi regla es esta:si hay algo que decir y el código poder no Si no hay forma de expresarlo, entonces puedes escribir un comentario.De lo contrario, si el código poder expresar la idea, entonces debes expresar la idea en el código o sus pruebas.

Si sigue esta regla, entonces su código sólo debería necesitar comentarios cuando se trate de algún problema no obvio en el hardware o el sistema operativo, o cuando el algoritmo más obvio no sea la mejor opción.Estos son comentarios de "esto es extraño porque", y en realidad son solo un mecanismo de afrontamiento. La mayoría de las veces, los comentarios en el código son en realidad solo disculpas por no escribirlo de una manera más obvia, y dichos comentarios deben obviarse y luego eliminarse.

Incluso los buenos comentarios a menudo se convierten en mentiras con el tiempo, por lo que la información que se encuentra en lugares no ejecutables ni comprobables, como los comentarios, debe considerarse con sospecha.Nuevamente, la respuesta es primero obviar el comentario y luego eliminarlo.

Mi proporción ideal es cero.Sin embargo, el mundo no es ideal, por lo que acepto comentarios cuando no hay otra forma de comunicar una idea importante.

Debería haber comentarios allí donde los considere necesarios.Ni más ni menos.

Comenta las partes que crees que quizás no entiendas después de más de 6 semanas de descanso al volver a mirar el código.

Intento mantener los comentarios al mínimo.El código debe explicarse por sí mismo y, aunque el código fuente tiende a cambiar, los comentarios casi siempre quedan atrás como una explicación incorrecta.

La proporción código áureo/comentario es la intersección de

comentarios necesarios para recordar las cosas que tenía en mente mientras codificaba
comentarios necesarios para recordar a los demás las cosas que tenía en mente mientras codificaba
comentarios por los que su cliente está dispuesto a pagar (porque los buenos comentarios cuestan tiempo)
el interés del desarrollador en producir código ofuscado debido a la seguridad laboral (si trabaja para una empresa donde un desarrollador puede salirse con la suya)

Esto también muestra por qué esa proporción es diferente para cada proyecto y cada equipo.

No existe una proporción áurea.La cantidad de comentarios depende en gran medida de la complejidad inherente del código.Si sólo estás escribiendo aplicaciones CRUD, probablemente no necesites muchos comentarios.Si está escribiendo un sistema operativo o un RDBMS, probablemente necesitará hacer más comentarios, ya que realizará una codificación más complicada y necesitará dejar un poco más explícito por qué está haciendo las cosas que está haciendo.

Si desea obtener datos del mundo real sobre las proporciones de comentarios para diferentes idiomas, eche un vistazo a Ohloh.

Como ejemplo, puedes mirar el varias métricas para la fuente del kernel de Linux.

Supongo que nadie puede darte cifras, pero debería ser mucho mayor en los archivos de encabezado que en el código fuente.

Esperaría que el archivo de encabezado de una clase documente todas las clases/funciones/etc. accesibles públicamente al incluir ese archivo de encabezado.Pueden ser muchas líneas para documentar una función cuyo prototipo es una sola línea (no, simplemente elegir buenos nombres para las funciones y sus parámetros no es suficiente; puede serlo, pero a menudo no lo es).Tres líneas de comentario por cada línea de código no serían excesivas.

Para el código real, sería mucho menor.No estoy de acuerdo con los extremistas que piensan que se debe aspirar a cero comentarios, pero ciertamente, si cree que necesita comentarios, primero debe considerar si el código podría aclararse más.

Puede variar bastante.Por ejemplo, puedes tener un código tan bien escrito que los comentarios serían una pérdida de tiempo.

Necesita suficientes comentarios para que meses después pueda mirar su código, leer el comentario y continuar donde lo dejó, sin mucho esfuerzo.Si no se requiere la historia de vida del código, no la escriba.

No existe una buena proporción de comentarios a código.En los viejos tiempos algunas personas creían que era necesario tener un comentario al principio de cada función explicando lo que hace.

Sin embargo, con la llegada de los lenguajes modernos, el código prácticamente se autodocumenta.Esto significa que las únicas razones que quedan para poner un comentario en el código son explicar de dónde vino una decisión extraña o ayudar a comprender un tema realmente complicado.

No existe una "proporción áurea".Depende del idioma y de la forma en que lo escribas.Cuanto más expresivo sea su código, más autodocumentado podrá ser y, por lo tanto, menos comentarios necesitará.Ésa es una ventaja de las interfaces fluidas.

No puedes exigir una proporción fija de código/comentarios, de lo contrario terminarás con un código lleno de ruido como:

// Add one to i
i++;

lo que simplemente nubla el código.

En lugar de eso, observe la complejidad del código y vea lo que necesita explicar, es decir,lógica, por qué se utilizan ciertos números mágicos, qué suposiciones existen con respecto a los formatos entrantes, etc.

Active su mentalidad de mantenedor y piense qué le gustaría que se describiera con respecto al código que acaba de escribir.

HTH.

salud,

Robar

Los comentarios tienen 3 usos, en mi opinión:

Explicar por qué el código hace lo que hace
Documentar la interfaz de un módulo.
Explicar por qué no se adoptaron otros enfoques para una parte de la lógica.

Si el código hace algo lo suficientemente básico como para que el por qué está claro, que debería ser la mayor parte del tiempo en la mayoría de los dominios, entonces los comentarios dentro de la lógica deberían ser mínimos...incluso acercándose a ninguno.Los comentarios nunca deben explicar el qué (con posibles excepciones para decir, por ejemplo, que la función es una implementación del algoritmo Foo como se explica en la Publicación del Colegio de Abogados).Si necesitas explicar qué lo estás haciendo, lo estás haciendo mal.

Hay una excelente discusión sobre los comentarios de código en el libro Code Complete de Steve McConnell () (tengo la primera edición pero creo que ahora es una segunda edición). Texto del enlace)

En resumen, refuerza lo que dijeron las otras respuestas: debería ser raro y describir el por qué y no el cómo; si puede refactorizar los nombres de variables y métodos para reemplazar los comentarios, entonces debería preferirse, y la mayoría de los IDE ofrecen algún tipo de intellisense (o como yo). una vez escuché a Don Box describirlo como - intellicrack debido a su carácter adictivo) no hay razón para truncar los nombres de variables/métodos cuando una versión más larga y clara comunicaría su intención más claramente

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

¿Un comando implícito "Haz lo que quiero decir" con un comentario "sin comentarios"?

No existe tal proporción.

Por lo general, los comentarios solo deberían aparecer en situaciones en las que algo pueda no estar realmente claro, como

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

Por otro lado, si le estás vendiendo Código a alguien, necesitarás tantos comentarios como sea posible.Imagen de venta de un motor 3D o algún otro middleware de juegos que no tiene comentarios.Claro, documentación API, etc.También son una gran parte de este tipo de Middleware, pero un buen código comentado también vale la pena.Cosas como "Agregar 1 a i" siguen siendo demasiado spam, pero algo como "CreateDevice() verificará primero si DirectX 10 está disponible y recurrirá al dispositivo DirectX 9 si no", puede ser realmente útil, incluso si es trivial. ver en el código.

Generalmente, el Código Interno suele estar mucho menos comentado que el código que usted vende, pero pueden aplicarse excepciones.

Me gusta usar comentarios para anotar código que me aseguro de que sea fácil de leer y tenga variables informativas.Dicho esto, me gusta intentar escribir cada línea de código para que, si es posible, sea tan informativo como un comentario.Debería poder tener una idea muy clara de lo que hace el código antes de leer los comentarios, o lo estará haciendo mal.

entre el 3% y el 9,5%, más o menos

Debo decir que vine aquí buscando una respuesta sobre 2 comentarios por 1 línea de código.Aunque esto sea una exageración, ¡va en la dirección correcta!En cambio, veo gente que recomienda tratar los comentarios como si fueran trufas u otros bienes raros.Desde una perspectiva peculiar del mundo académico, donde la calidad del código es baja y el uso del control de versiones es aún más raro que las trufas, instaría a cualquiera a escribir tantos comentarios como sea posible, incluso en contra de su propio juicio sobre si el comentario es 100% necesario.

Los comentarios te hacen la vida más fácil porque es probable que estés pensando, ¡en qué diablos estaba pensando al escribir esto!

Licenciado bajo: CC-BY-SA con atribución

No afiliado a StackOverflow