Estándar de codificación para mayor claridad: ¿comentar cada línea de código?

142

He trabajado en tiendas que producen software crítico para la vida y me he ocupado de las reglas de comentarios destinadas a mantener el código legible y potencialmente salvar vidas. En mi experiencia, sin embargo, el requisito se convierte en una tarea de muerte cerebral para ser eliminada de una lista de verificación y no me ayuda a mantenerme enfocado en escribir código comprensible. También distrae a mi revisor de tener una conversación más significativa conmigo sobre cómo hacer que el código sea más fácil de entender.

También califiqué el código del estudiante que no tenía comentarios y vi por qué deberían marcarse por descuidarlos.

Entiendo que usar buenos nombres, mantener estructuras simples, funciones cortas y módulos enfocados mantendrá el código lo suficientemente comprensible para que los comentarios puedan ser minimizados.

También entiendo que los comentarios deberían explicar por qué el código hace lo que hace, no cómo.

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea? Los que serán relevantes en una revisión por pares pero no se convertirán en una actividad de lista de verificación sin sentido que produce notas no más útiles que: "Olvidó comentar en la línea 42".

Un ejemplo del tipo de código que esta regla puede requerir cuando se trata como una línea en una lista de verificación:

/* Display an error message */
function display_error_message( $error_message )
{
    /* Display the error message */
    echo $error_message;

    /* Exit the application */
    exit();
}

/* -------------------------------------------------------------------- */

/* Check if the configuration file does not exist, then display an error */
/* message */
if ( !file_exists( 'C:/xampp/htdocs/essentials/configuration.ini' ) ) {
    /* Display an error message */
    display_error_message( 'Error: Configuration file not found. Application has stopped');
}

Si es posible expresar esto correctamente en un documento estándar, y simplemente podría no serlo, me gustaría capturar una idea en este sentido:

Considere un comentario para cada línea, secuencia, declaración, sección, estructura, función, método, clase, paquete, componente, ... de código. Luego considere renombrar y simplificar para eliminar cualquier necesidad de ese comentario para que pueda eliminarlo. Regístrese mientras los comentarios son raros. Repita hasta la fecha límite. Luego repite un poco más

naranja confitada
fuente
21
Los comentarios no son para discusión extendida; Esta conversación se ha movido al chat .
maple_shaft
32
"Los comentarios no son para una discusión extensa" incluso más cierto para los comentarios de código. :) Esos /* Display an error message */comentarios son horribles y en realidad impactan la legibilidad.
Andrea Lazzarotto
Necesitamos que nuestros IDE tengan opciones para ocultar comentarios. Tal vez una opción para bloquear y comentar en línea se oculte por separado. De esta manera tienes lo mejor de ambas opciones. Agregue muchos comentarios, pero tenga la opción de ocultarlos para mantener el código limpio y ordenado.
Doug.McFarlane
1
@ Doug.McFarlane Pensé que debería existir para vim. Por supuesto, lo hace tanto a nivel de archivo como de bloque: rtfm-sarl.ch/articles/hide-comments.html .
Michael Durrant
1
También alternar - stackoverflow.com/a/11842371/631619
Michael Durrant

Respuestas:

171

La respuesta de Michael Durrant es en mi humilde opinión, no está mal, pero no responde literalmente a la pregunta (como él mismo admitió), por lo que intentaré dar una respuesta que sí:

También entiendo que los comentarios deberían explicar por qué el código hace lo que hace, no cómo.

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea?

Obviamente, puede escribir una lista de verificación para sus revisiones de código , que contiene preguntas como

  • "si hay un comentario, ¿explica por qué el código hace lo que hace?"
  • "¿cada línea del código, en su contexto, se explica por sí misma lo suficiente como para que no necesite un comentario, o si no, va acompañada de un comentario que cierra esa brecha? O (preferiblemente) ¿se puede cambiar el código para ya no necesita un comentario? "

Si lo desea, puede llamar a esto un "estándar de codificación" (o no, si cree que el término estándar de codificación debe reservarse para una lista de reglas de braindead, fácil de responder si se cumplen o no, cómo se formatea el código debería verse como, o dónde declarar variables). Nadie le impide enfocarse en su lista de verificación en preguntas semánticas , en lugar de seguir la ruta fácil y poner solo reglas formales .

Al final del día, debe estar seguro de que su equipo necesita dicha lista de verificación. Para aplicar estas preguntas, necesita programadores con cierta experiencia como revisores, y debe averiguar si realmente mejorará la legibilidad del código en un equipo de expertos. Pero eso es algo que debes resolver junto con tu equipo.

Doc Brown
fuente
45
¿Quién rechazó esto? Esta es la respuesta para el desarrollo de software crítico. Este es un mundo diferente en comparación con donde trabaja la mayoría de los programadores. En estos mundos, un estándar de codificación que exige que cada línea de código tenga su propio comentario no es la respuesta correcta. Tampoco se renuncian los comentarios. OTOH, hacer comentarios sujetos a revisión de código es exactamente el tipo correcto de estándar para software crítico. Hace que el código sea más revisable y mantenible, pero esto tiene un costo. Ese costo palidece en comparación con las demandas multimillonarias que han resultado de un software mal escrito.
David Hammen
44
sabia respuesta. Si pudiéramos encontrar reglas genuinas para la codificación, no necesitaríamos programadores. podríamos tener el código de la máquina. ¡podría ocurrir! :(
44
@DavidHammen: gracias por tu comentario. En realidad, creo que esto no solo se aplica al "desarrollo de software crítico". Cada pieza de software que se mantiene y evoluciona durante años, a menudo por diferentes personas, se beneficiará de ser comprensible para el próximo programador de mantenimiento.
Doc Brown
55
Este es un buen consejo para cualquier codificación, no solo para el código mantenido por diferentes personas. Incluso si usted es el único que usa un script / programa, el futuro que tenga que modificar el código en un año apreciará la claridad (y el tiempo ahorrado al no tener que descifrar el código opaco).
Anthony Geoghegan el
55
¿Podría editar "la respuesta más votada actualmente" a algo más objetivo? No todos los lectores conocerán el historial de votos de estas respuestas.
candied_orange
151

Gran antipatrón que conduce a un código de baja calidad con menos claridad.

por cierto lectores, el título originalmente era "¿comentar cada línea de código?" y puedes imaginar la reacción instintiva de muchos de nosotros, incluido yo mismo. Más tarde volví al título más largo y preciso.

Al principio, al leer su pregunta, pensé, duplicar cosas en los comentarios, pero está bien, tal vez si tiene suficientes restricciones en las revisiones de varias personas ... pero, de nuevo: la gente comete errores, no nota inconsistencias, etc. y con el tiempo terminará habiendo diferencias. Reflexionando, creo que el problema es mucho mayor:

Los desarrolladores tenderán a escribir código peor. Usarán más nombres y estructuras crípticas porque 'se explica en el comentario, ¡mira!'.

Considerar:

living_room_set = tables + chairs.

Ahora considere:

set = tbls+chrs # Make the set equal to the table plus the chairs

No solo tiene más nombres crípticos y más para leer, sino que también tiene que mirar hacia adelante y hacia atrás, mirar el código, ¿qué es un conjunto? mire a la izquierda en el código, mire a la derecha en los comentarios, qué son tbls, mire a la izquierda en el código, mire a la derecha en los comentarios, qué son los caracteres, mire a la derecha en el comentario. Yuch!

Resumen

Desarrolle o mejore un estándar de comentarios si se ve obligado a hacerlo en su posición actual como desarrollador (como programador anterior de COBOL, ¡he visto grandes!), Pero pasó la mayor parte de su tiempo, energía y pasión discutiendo en contra del comentario. patrón usando los argumentos:

  • El código y los comentarios no se sincronizan entre sí cuando solo se cambia uno

  • Los comentarios pueden describir lo que piensa una persona, pero pueden estar equivocados y, por lo tanto, ocultar errores

  • El código se vuelve más difícil de leer

  • El buen código se vuelve más difícil de escribir

  • Tendencia a usar más nombres crípticos

  • Caracteres excesivos para leer en código y comentarios

  • Diferentes editores usan diferentes estilos

  • Requiere mayor dominio del idioma inglés que solo codificar

  • Toma tiempo y recursos y resta del valor a largo plazo *

Además, defienda un código mejor sin tales comentarios, de hecho, tenga un estándar (!). Todos los nombres de variables deben ser full_english_words. ¡Hay uno! Así que usa esa energía de "estándares" hacia los estándares de código y pruebas bien escritos.

Uno de los dos problemas difíciles es nombrar cosas: no omita el problema con comentarios.

Dado que uno de los otros problemas es la optimización prematura y que la optimización en general puede conducir a un oscuro código de "por qué de esta manera", esta es un área donde los comentarios explicativos para un código aparentemente deficiente pueden ser beneficiosos, aunque las advertencias anteriores todavía se aplican.

* código de mañana

Michael Durrant
fuente
8
No creo que hayas respondido la pregunta. La pregunta no se trata de tener comentarios en cada línea. Se pregunta cómo decirle a los desarrolladores que comenten el código sin hacer que comenten cada línea.
hichris123
77
Sí, no estoy respondiendo la pregunta de estándares específicos, sino que estoy tratando de ayudar a la gente a no seguir ese camino. Por lo tanto, esta puede no ser la respuesta a la pregunta específica, pero contiene consejos valiosos que son difíciles de exponer en un comentario.
Michael Durrant
1
¿Cuál es el otro problema difícil?
David Grinberg
20
@DavidGrinberg invalidación de caché y errores fuera de uno .
Eric King el
1
Cada una de sus razones para evitar comentarios se puede contrarrestar, pero StackExchange no permite comentarios lo suficientemente largos (heh) para que pueda abordarlos todos aquí. Simplemente: comentar en exceso es como fraude electoral: sucede, pero muy raramente; ¿Cuándo es la última vez que lo viste? Escribir buenos comentarios no debería ser simplemente una idea de último momento; Si se hace correctamente, ayuda al proceso de desarrollo. Sí, requiere recursos, pero la recompensa es un mejor código. Nunca podrá obtener el mismo rendimiento por su dinero sacrificando comentarios por un mejor estándar de nomenclatura variable. Sí, comentar cada línea es una locura.
kmoser
23

No creo que un documento de estándares de codificación sea el lugar para especificar lo que ya es de sentido común. El propósito de un estándar de codificación es garantizar la coherencia (y evitar discusiones) sobre cuestiones en las que personas razonables pueden estar en desacuerdo y no hay una respuesta correcta obvia, por ejemplo, convenciones de nombres, sangría, etc.

Los comentarios como en su ejemplo son objetivamente inútiles y pueden deberse a un desarrollador sin experiencia, o un desarrollador que solía trabajar con un sistema de compilación que verifica mecánicamente la presencia de comentarios (una idea realmente mala, pero existe). En ambos casos, la solución es la educación, posiblemente a través de revisiones de código.

Si comienza a agregar todo tipo de "mejores prácticas" al estándar de codificación, terminará repitiendo lo que ya se ha indicado en varios libros. Simplemente compre "Clean Code", "Code Complete" y "The Pragmatic Programmer" al desarrollador en cuestión, y mantenga su codificación estándar.

JacquesB
fuente
63
Una de las muchas cosas que he aprendido después de más de 40 años en esta raqueta es que el sentido común no es del todo común.
John R. Strohm
10
No existe el sentido común.
cuál es el
1
in_programming no .. mundo real oh sí, pero es solo un término para el conocimiento experimentado del mundo real
Michael Durrant
@ JohnR.Strohm: Mi experiencia ha sido mucho más positiva que la suya, pero también he visto cómo se puede desalentar activamente el uso del sentido común mediante la aplicación mecánica de reglas.
JacquesB
Estoy en un 99.9% de acuerdo con esta respuesta. El estándar de codificación está destinado a ser lo que los desarrolladores señalan cuando se produce un debate en Code Review. La revisión del código está destinada a enriquecer el producto, no a iniciar guerras. Tantas guerras que he visto instigadas por Revisiones de Código sin Estándar de Codificación. Me atrevo a decir que si no puede automatizar la verificación de los elementos en el estándar de codificación, debería estar allí. Una revisión del Código es el momento de impartir "sentido común" a otros desarrolladores menos experimentados. No es el momento de pelear por nombrar variables. linux / kernel / gen_init_cpio.c línea 335.
Andrew T Finnell el
19

No es posible. Lo que esencialmente está tratando de hacer es casi mecanizar el buen juicio.

Al escribir software crítico, como para sistemas médicos de soporte vital, grandes cantidades de listas de verificación y demás son prácticamente inevitables. No solo las personas inteligentes cometen errores, sino que gran parte del software para estos dispositivos está escrito por personas que no son muy buenas en sus trabajos, por lo que el 'sistema' debe ser capaz de protegerse contra el trabajo descuidado, haciéndolo seguro en El gasto de comercialización.

Su mejor opción es dejar de lado el riguroso estándar de codificación para comentar y liderar al equipo con el ejemplo. Muestre a otros cómo se ven los buenos comentarios esforzándose por producir un código de buena calidad que esté debidamente comentado. En lugar de tratar de encontrar la mejor manera de describir cómo escribir comentarios (que a menudo son una llamada de juicio), muestre a los demás lo que quiere decir a diario con sus propias revisiones de código. A medida que los otros miembros lean su código, seguirán su ejemplo si lo consideran útil. Y si no pueden, entonces ninguna Norma les ayudaría a escribir mejores comentarios para empezar.

whatsisname
fuente
1
+1 para "Estás tratando de mecanizar el buen juicio", -1 para "Tu única opción es esperar lo mejor", y eso me deja sin votar. Educar y capacitar a su equipo también es una opción. Las normas pueden permitir el juicio.
Comodín el
1
@Wildcard ¿Quizás podría explicar cómo un Estándar puede permitir el juicio? ¿No sería eso una guía en ese momento? Un estándar es "una idea o cosa utilizada como medida, norma o modelo en evaluaciones comparativas". ¿Cómo se puede usar algo inherentemente subjetivo, tan subjetivo que depende de quién lo está leyendo, como una medida de calidad?
Andrew T Finnell el
1
@Wildcard: El problema es que cuando ingresas a industrias reguladas, el proceso reina por encima de todo, tener un proceso es más importante que si el proceso vale la pena o no. Todo tiene que reducirse a casillas de verificación de alguna forma, cada casilla de verificación debe ser específica y verificable, y cuanto más margen de libertad tenga en una casilla de verificación, más riesgo corre de ser molestado en una auditoría.
cuál es el
Es un mundo extraño, y tenga en cuenta que las reglas están escritas por burócratas con poco conocimiento del dominio del software, y a menudo termina con sistemas que existen para justificarse y exigirse a sí mismos en lugar de ser un medio para un fin para garantizar productos de calidad.
cuál es el
1
@whatsisname Estoy muy feliz de que haya alguien más que entienda. Sus respuestas están escritas con más elegancia y precisión de lo que podría haber luchado. La declaración with systems that exist to justify and require themselves rather than being a means to an end to ensure quality productses EXACTAMENTE lo que intentaba ilustrar. Gracias por encontrar mis palabras para mí. Realmente lo digo en serio. Tenemos que separar la idea de inducir calidad de la idea de seguir un proceso ya que no son lo mismo. Es por eso que tenemos QA, Stackoverflow y clientes muy indulgentes.
Andrew T Finnell el
14

Actualizar

Mi respuesta entre comillas para enfatizar:

Creo que la respuesta que establece que los comentarios no deben abordarse en los Estándares de codificación y luego enumera un conjunto de preguntas defensivas para combatirla, es la única respuesta correcta.

El problema aquí es que un estándar de codificación es solo eso, un estándar . Las ideas extremadamente subjetivas no deberían estar en un estándar de codificación . Puede estar en una guía de Mejores Prácticas, pero esa guía no se puede usar contra un desarrollador durante la Revisión de Código. En mi opinión personal, un estándar de codificación debe ser lo más cercano posible a la automatización. Hay mucho tiempo perdido en las revisiones de código discutiendo sobre nombres, espacios, pestañas, corchetes, comentarios, etc., etc., cuando TODO se puede automatizar. Incluso la respuesta sobre tablesy chairsse puede automatizar. LINT'ers permite diccionarios, verificaciones de capitalización por concepto (variable, función, método, clase, etc.).

Incluso la comprobación de JavaDoc puede ser implementada por un Robot LINT'er antes de que se acepte una solicitud de extracción. Muchos proyectos de código abierto hacen exactamente esto. Envíe su solicitud de extracción, el código se crea con un archivo Travis-CI, incluido el análisis estático, y debe pasar todos los estándares de codificación que pueden expresarse objetivamente. No hay señales humanas sobre 'hacerlo incorrectamente' o no 'proporcionar valor' con un comentario, o la forma incorrecta de nombrar variables, et el. Esas discusiones no aportan ningún valor y es mejor dejarlas en manos de un robot de terceros que pueda recibir la peor parte de nuestra codificación emocional.

Para responder realmente a la pregunta, deberíamos abordar cómo escribir un Estándar que aborde cómo responder a la siguiente pregunta: ¿Este comentario proporcionó valor? Un estándar de codificación no puede dictar el 'valor' de un comentario. Por lo tanto, se hace necesario que un humano revise esa lista de verificación. La mera mención de comentarios en un Estándar de codificación crea una lista de verificación que el Cartel original quiere evitar.

Es por eso que los comentarios generalmente no son procesados ​​por el compilador y eliminados. Su valor no puede determinarse. ¿Es valioso el comentario en cuestión? ¿si o no?. Responder esta pregunta es NP-hard. Solo los humanos tienen la oportunidad de responderlo adecuadamente, e incluso entonces solo puede ser respondido en el momento en que se lee, por la persona que lo está leyendo; donde el valor de ese comentario se ve afectado por el clima, su vida hogareña, la última reunión a la que asistieron y no terminó bien, la hora del día, la cantidad de café que tomaron. Confío en que la imagen se está volviendo más clara.

¿Cómo puede expresarse correctamente en alguna Norma? Un estándar no es útil a menos que se pueda aplicar de manera consistente y justa, donde lo justo es más sobre la objetividad y no emocional.

Confieso que un estándar de codificación debe permanecer tan objetivo como sea posible. La forma en que las variables se denominan objetivo IS. Pueden verificarse fácilmente en un diccionario para determinar la ortografía, la estructura gramatical y la carcasa adecuadas. Cualquier cosa más allá de eso es un "partido de meado" que gana la persona con más poder o "golpe de cejas". Algo que, personalmente, me cuesta no hacer.

Cuando comento, siempre comento hablar con mi futuro yo en tercera persona. Si vuelvo a este código en 5 años, ¿qué necesito saber? ¿Qué sería útil, qué sería confuso y qué estaría desactualizado con el código? Existe una diferencia entre el código de documentación para generar una API pública de búsqueda y el código de comentario que proporciona valor a un tercero desconocido, incluso si ese tercero es usted mismo.

Aquí hay una buena prueba de fuego. Si fueras el ÚNICO en el proyecto. Sabías que serías el único en el proyecto. ¿Cuál estaría en su estándar de codificación? Desearía que su código sea claro, autoexplicativo y comprensible para usted en el futuro. ¿Tendrías una revisión de código contigo mismo sobre por qué no pusiste un comentario en cada línea? ¿Revisaría cada comentario que creó en los 100 archivos que registró? Si no, ¿por qué obligar a otros?

Algo que creo que se pierde en estas discusiones es que Future You también es un desarrollador de este proyecto. Al preguntar sobre el valor, mañana usted también es una persona que puede obtener valor del comentario. Entonces, el tamaño del equipo, en mi opinión, no importa. La experiencia del equipo no importa, cambia con demasiada frecuencia.

Ninguna cantidad de código de comentario que revise esto evita que un marcapasos se estrelle y mate a un paciente. Una vez que habla de un comentario que afecta el código, ahora está hablando del código, no del comentario. Si todo lo que se necesita es un comentario faltante para matar a alguien, hay algo más que huele en el proceso.


La solución a este tipo de codificación rigurosa ya se ha proporcionado como una metodología para escribir el software en sí. Y no tiene nada que ver con los comentarios. El problema con los comentarios es que NO tienen impacto en la forma en que funciona el producto. Los mejores comentarios del mundo no pueden evitar que el software se bloquee cuando está integrado en un marcapasos. O al medir las señales eléctricas con un electrocardiograma portátil.

Tenemos dos tipos de comentarios:

Comentarios legibles por máquina

Los estilos de comentarios como Javadoc, JSDoc, Doxygen, etc. son todas formas de comentar la interfaz pública que proporciona un conjunto de códigos. Esa interfaz solo puede ser utilizada por otro desarrollador único (código de propiedad para un equipo de dos personas), un número desconocido de desarrolladores (por ejemplo, JMS) o para un departamento completo. Este código puede leerse mediante un proceso automatizado que luego produce una forma diferente de leer esos comentarios, como HTML, PDF, etc.

Es fácil crear un estándar para este tipo de comentario. Se convierte en un proceso objetivo de asegurar que cada método, función, clase públicamente invocable contenga los comentarios requeridos. Encabezados, parámetros, descripción et. el. Esto es para garantizar que sea fácil para otro equipo encontrar y usar el código.

Estoy haciendo algo que parece loco, pero realmente no

Estos comentarios están aquí para ayudar a otros a ver POR QUÉ este código fue escrito de cierta manera. Quizás haya un error numérico en los procesadores en los que se está ejecutando el código y siempre se redondea, pero los desarrolladores suelen lidiar con el código que se redondea. Por lo tanto, comentamos para asegurarnos de que un desarrollador que toca el código entienda por qué el contexto actual está haciendo algo que normalmente parece irrazonable, pero en realidad se escribió de esa manera a propósito.

Este tipo de código es lo que causa tantos problemas. Por lo general, no se comenta y luego es encontrado por un nuevo desarrollador y 'arreglado'. Rompiendo así todo. Incluso entonces, los comentarios solo están ahí para explicar el POR QUÉ no evitar que algo se rompa.

No se puede confiar en los comentarios

Los comentarios son en última instancia inútiles y no se puede confiar. Los comentarios normalmente no cambian la forma en que se ejecutan los programas. Y si lo hacen, entonces su proceso está causando más problemas de lo que debería. Los comentarios son ideas posteriores y nunca pueden ser otra cosa que no sea. El código es todo lo que importa, ya que es todo lo que procesa la computadora.

Esto puede sonar tonto, pero tengan paciencia conmigo. ¿Cuál de estas dos líneas realmente importa?

// We don't divide by 0 in order to stop crashes.

return 1 / n;

En este ejemplo, todo lo que importa es que no tenemos idea de qué es 'n', no hay ninguna verificación de que n sea 0 E incluso si lo hubiera, nada impide que un desarrollador ponga n = 0DESPUÉS de la verificación de 0. Por lo tanto, el comentario es inútil y nada automatizado puede captar esto. Ningún estándar puede atrapar esto. El comentario, aunque bonito (para algunos) no tiene relación con el resultado del producto.

Desarrollo guiado por pruebas

¿Qué tiene un resultado en el producto? Las industrias en las que el código que se está escribiendo literalmente puede salvar o matar a alguien deben ser rigurosamente controladas. Esto se hace a través de revisiones de código, revisiones de código, pruebas, pruebas, revisiones de código, pruebas unitarias, pruebas de integración, ensayos, estadificación, meses de prueba, revisiones de código y ensayos de una sola persona, puesta en escena, revisiones de código, prueba, y luego tal vez finalmente entrando en producción. Los comentarios no tienen nada que ver con nada de esto.

Prefiero codificar que NO tenía comentarios, tenía una especificación, tenía pruebas unitarias que verificaban la especificación, estudios de los resultados de ejecutar el código en el dispositivo de producción, luego un código bien documentado que nunca había sido probado, ni tenía nada para comparar el código en contra.

La documentación es agradable cuando intenta averiguar POR QUÉ alguien hizo algo de cierta manera, sin embargo, a través de los años he descubierto que la documentación se usa típicamente para explicar por qué se hizo algo "inteligente", cuando realmente no era necesario ser escrito de esa manera.

Conclusión

Si trabaja en una empresa que REQUIERE que se comente cada línea, GARANTIZARÉ que al menos dos de los ingenieros de software del proyecto ya han escrito un programa de documentación automática en Perl, Lisp o Python que determina la idea general de lo que está haciendo la línea. , luego agrega un comentario sobre esa línea. Debido a que esto es posible, significa que los comentarios son inútiles. Encuentre a los ingenieros que han escrito estos scripts para documentar automáticamente el código y úselos como evidencia de por qué el "Comentario en cada línea" está desperdiciando tiempo, sin proporcionar valor y potencialmente perjudicando.

Por otro lado, estaba ayudando a un amigo cercano con una tarea de programación. Su maestro había establecido el requisito de que cada línea debía ser documentada. Entonces puedo ver de dónde vendría este proceso de pensamiento. Pregúntese, ¿qué está tratando de hacer? ¿Es esto lo correcto? Entonces pregúntate a ti mismo; ¿Hay alguna forma de 'jugar' el sistema con este proceso? Si lo hay, ¿está realmente agregando algún valor? Uno no puede escribir automáticamente pruebas unitarias que prueben que el código cumple con una determinada especificación, y si pudieran, eso no sería malo.

Si un dispositivo tiene que funcionar bajo ciertas condiciones porque estará dentro de un ser humano, la única forma de asegurarse de que no los matará es años de pruebas, revisión por pares, ensayos y NUNCA vuelva a cambiar el código. Esta es la razón por la cual la NASA todavía está / estaba usando hardware y software tan antiguo. Cuando se trata de la vida o la muerte, no solo "hace un pequeño cambio y lo registra".

Los comentarios no tienen nada que ver con salvar vidas. Los comentarios son para humanos, los humanos cometen errores, incluso cuando escriben comentarios. No confíes en los humanos. Ergo, no confíes en los comentarios. Los comentarios no son su solución.

Andrew T Finnell
fuente
3
El problema con los comentarios es que NO tienen impacto en la forma en que funciona el producto. Si bien la parte humana de lectura y escritura de los recuentos de código pienso que qué afecta la forma en que en última instancia, funciona, pero no cómo el código se ejecuta cuando finalmente escrita, sí. ¡Diría que EL problema con el código es simplemente que se desactualiza y es peor que no tener código!
Michael Durrant
1
Aquí, teníamos un cronometrador que quería informes diarios de lo que hacíamos para poder optimizar nuestro trabajo. En cualquier caso, estábamos un poco enojados por el hecho de que necesitábamos pasar 15 minutos cada día llenando su formulario, así que automatizamos esto al llenar la basura de nuestros registros.
joojaa
1
Hay un problema adicional con el comentario "No dividimos entre 0 para detener los bloqueos". No está claro gramaticalmente si la cláusula "con el fin de" se aplica a la acción de división o a su negación. Si usa "Evitamos dividir por 0 para ...", evitará esta ambigüedad. :)
Comodín el
1
"no dividir entre cero para detener los accidentes" en realidad me dice mucho sobre la mentalidad de la persona que lo escribió. ¡No codificas para evitar accidentes! Codifica para que el código sea correcto, y no fallar es solo una pequeña parte de ser correcto. Si el cálculo de la cantidad de medicamento para inyectar termina dividiéndose entre cero, no devuelve un valor ficticio como 99999 ...
immibis
1
@AndrewTFinnell Quiero decir que si a veces obtienes un error de división por cero, agregar "if (divisor == 0) return <something>; // evitar la división por cero" no hace que tu código sea más correcto. En su lugar, debe encontrar por qué el divisor es cero y solucionarlo. Algunos algoritmos están diseñados para que el divisor cero sea inevitable, pero son la excepción (y en ese caso puede devolver un valor de "no se puede calcular el resultado").
Immibis
12

Hay dos cosas diferentes a las que alude cuando habla de comentarios. No son lo mismo, y la distinción es importante.

La documentación le informa sobre los bits externos de un fragmento de código: su interfaz.

Por lo general, las herramientas le permitirán leerlos de manera 'independiente', es decir, no está mirando el código subyacente al mismo tiempo.

Toda la interfaz debe estar documentada (por ejemplo, cada método, excluyendo los métodos privados), y debe describir entradas, salidas y cualquier otra expectativa, limitación, etc., especialmente cosas que no se pueden expresar a través de restricciones, pruebas, etc. ( La cantidad exacta de detalles y hacia dónde va depende del proyecto).

Una buena documentación permite al consumidor potencial decidir si, cuándo y cómo usar el código.

Los comentarios en el código fuente tienen un propósito diferente. Están ahí para las personas que miran el código fuente. Principalmente describen la implementación.

Los comentarios siempre se leen entre el código subyacente.

Los comentarios deben explicar decisiones sorprendentes o algoritmos complejos, o de opciones no tomadas (y razonamiento). Están allí para que los futuros desarrolladores puedan comprender los procesos de pensamiento de sus predecesores y tengan a mano información que de otro modo podrían pasar por alto o pasar mucho tiempo buscando, por ejemplo

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

No puede inferir nada de la ausencia de un comentario, y el comentario puede, por supuesto, ser tan incorrecto como el código circundante o más. El juicio debe ejercerse tanto por parte del autor como por parte del lector.

Comentar cada línea es claramente más trabajo de valor adicional cuestionable, que viene con un costo de oportunidad. Si tiene una regla que dice que cada línea debe ser comentada, la obtendrá, pero a expensas de que las partes importantes se comenten bien .

Pero es peor que eso: el propósito de un comentario es derrotado si se comenta cada línea. Los comentarios se convierten en ruido que hacen que el código sea difícil de leer: oscurece en lugar de aclarar. Además, los comentarios indiscriminados hacen que los comentarios verdaderamente importantes sean más difíciles de detectar.

Ni los comentarios ni la documentación proporcionan ningún tipo de medida o garantía de la calidad del código que describen; no son un reemplazo para el control de calidad genuino. Su propósito es mirar hacia el futuro, es decir, con la esperanza de ayudar a quienes interactúan con él a evitar cometer errores.

En resumen , sus estándares de codificación pueden y deben requerir documentación (las comprobaciones automáticas ayudan a detectar funciones / métodos no documentados, pero los humanos aún deben verificar si la documentación es buena). Los comentarios son una decisión, y su guía de estilo debería reconocerlo. Los que nunca comentan y los que comentan sin pensar deberían esperar ser desafiados.

usuario52889
fuente
Documentar la API pública es un buen punto, pero realmente me gusta explicar decisiones sorprendentes. Es muy agradable si las violaciones del principio de mínimo asombro al menos vienen con una justificación. +1
candied_orange
1
+1 para comentarios extraños como ruido. Mantenga la señal al ruido alto.
sq33G
+1 especialmente con el propósito de un comentario es derrotado si cada línea es comentada. Lástima que esto podría usarse (y a menudo se usa) como una excusa para no comentar en absoluto, pero de todos modos es muy correcto, por las razones que mencionó, más porque si se comenta cada línea, la mayoría de las personas comenzarán a ignorar todos los comentarios de manera automática y comprensible. .
SantiBailors
10

No puede codificar un estándar de comentarios, porque no puede saber cuál será el comentario importante de antemano.

Pero aún así desea asegurarse de que el código se comente correctamente, ya que este es un código vital. La solución es tener un estándar para la revisión del código : requiere que el comentario del código comente sobre la comprensibilidad.

Esto no garantizará que no se convierta en una lista de verificación sin sentido, pero al menos evitará que el código sea más difícil de leer. Y tiene la posibilidad de mejorarlo.

Esto requiere una cultura en la que una revisión de código no sea en sí misma un gesto sin sentido, en el que enviar su código de regreso como algo difícil de leer sea algo bueno, y no un insulto o molestia. Igual de importante, uno donde decir que no estaba claro, no se ve como un fracaso del lector.

El código ilegible es, hasta cierto punto, inevitable. Porque el escritor está inmerso en el contexto y verá algo obvio cuando solo es obvio si conoce x, y o z.

Por lo tanto, no podrá tener una regla que diga dar buenos comentarios, pero puede verificar las revisiones. Incluso un administrador no programador podría hacerlo, porque la verdadera pregunta no es si el código escrito es legible, sino el código realmente legible, que solo puede decidir alguien que lo lea.

jmoreno
fuente
77
Re No puede codificar un estándar de comentarios : claro que puede. Los comentarios están sujetos a revisión de código, y ese elemento de revisión de código que dice que los comentarios no explican el código debe ser abordado. Este es un gasto, un gasto que la mayoría de los entornos de programación no quieren pagar. Vale la pena con respecto al software crítico.
David Hammen
"... cuando solo es obvio si sabes x, y o z" ​​Podrías especificar la cantidad de conocimiento {x, y, z} que necesitas saber de antemano para ver algo tan obvio y luego (tipo de forma mecánica) puede verificar si esto es cierto para el código actual. Donde no, agregue comentarios hasta que lo sea.
Trilarion
1
@DavidHammen: ese no es un estándar para el comentario, es un estándar para la revisión. Que es lo que sugerí como solución. No puede decir que tiene que tener un cierto tamaño, o usar una sintaxis particular o incluso requerir un comentario útil en primer lugar (u obtiene comentarios de tipo "agregar uno a i"). PUEDE decir que el revisor debe comentar el código y los comentarios. Como usted dice, puede requerir que se aborden los problemas planteados por la revisión del código. Pero la responsabilidad de esto TIENE que estar en el revisor para hacer un buen trabajo. Solo el revisor puede juzgar si el código y el comentario son suficientes.
jmoreno
@DavidHammen ¿Las personas elegidas para la revisión toman la decisión? ¿Y cuando se van? ¿Si las personas nuevas no piensan lo mismo o no hablan inglés? Si los 'revisores' se van? Su sugerencia coloca a algunos desarrolladores en la cima de una Torre de Marfil, lo que lleva a la disidencia, la desconfianza y la interrupción de la comunicación. Los comentarios están destinados a proporcionar información o aclaraciones para aquellos que pueden usarlo. Quizás Joe lo necesita, pero Mary no. ¿Qué sucede cuando Mary es la revisora? O Joe? O marca?
Andrew T Finnell el
@jmoreno: no colocar reglas / pautas sobre los comentarios en los estándares de codificación significa que los programadores tienen que buscar en múltiples fuentes, y no saben dónde buscar hasta que la revisión regrese diciendo que los comentarios son deficientes. Es un error pensar que todo en un estándar de codificación debe ser automatizable. Las reglas sobre nombres significativos, por ejemplo, no son automatizables. Al menos no todavía. Por ejemplo, x, y, y z, o i, jy kpueden ser nombres muy significativos si se está aplicando un algoritmo científica basada en un artículo de revista que utiliza exactamente esos nombres en sus fórmulas.
David Hammen
9

Comenta cada línea de código? No se .

El propósito de las otras reglas de las que hablas es precisamente evitar eso.

Los comentarios a un código legible son, en el mejor de los casos, redundantes, y en el peor de los casos, el lector se desviará buscando el propósito inexistente del comentario.

Si comenta un código completo que se explica por sí mismo, duplica la cantidad de lectura sin proporcionar información adicional. No estoy seguro de que tal redundancia valga la pena. Uno puede imaginarse a un crítico que dice que 42 dice " display_error" mientras que el comentario dice "muestra advertencia". Pero imagina un cambio en el código. Tienes dos lugares para corregir ahora. Queda claro que este estilo tiene negativos para copiar y pegar.

Yo diría que de manera óptima el código no debería necesitar ningún comentario, aparte de la documentación.

Hay estilos que son totalmente opuestos, si tiene dudas sobre la línea, es:

  1. El código es demasiado complicado y debe refactorizarse en una función con un nombre con un significado semántico para la parte del código. Ya sea un complejo ifo una parte de un algoritmo. (O un ingenioso LINQ one-liner)

  2. Si no puede simplificarse, no conoce suficientes expresiones idiomáticas.

(Personalmente, no soy un fanático de la estricta regla de no hacer comentarios, pero me parece una buena mentalidad inicial para seguir).

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea?

En cuanto al proceso. Nuestro estándar dio bastante crédito al revisor. Asumiendo que no son maliciosos, esto funciona bien.

Cuando pregunta "¿Qué es variable o?", Cambia el nombre. Si pregunta qué hace este bloque, refactorice o comente. Si hubo un debate sobre si algo está claro o no, si el revisor no lo entendió, entonces, por definición, no lo es. En muy raras ocasiones hubo algo así como la segunda opinión de algunos amigos.

En promedio, debe obtener un código comprensible para el programador promedio en el equipo. En mi opinión, evita la información redundante y garantiza que el código sea comprensible para al menos otro miembro del equipo, lo que encontramos un buen óptimo.

Además, no había absolutos . Aunque éramos un grupo pequeño. Es fácil encontrar consenso en el grupo de 5.

luk32
fuente
2
El uso de revisiones de código para dictar qué variables, clases y métodos deben nombrarse es la mejor manera de hacer que las personas odien una empresa, negocio o metodología. Las revisiones de código no deben usarse como una forma de hacer cumplir las cosas que realmente no importan. Un estándar de codificación debe ser verificable a través de un proceso automatizado. La longitud del nombre variable, la complejidad circular, la ley de Demeter, son todas las cosas que se pueden verificar. Si alguien me dijera que cambiara el nombre de una variable de 'i' a algo como indexForThePreviousCollection, encontraría otro lugar para trabajar. Las variables> 3 caracteres se verifican antes del check-in automáticamente.
Andrew T Finnell el
3
@ AndrewTFinnell Puedo escribir códigos imposibles de seguir en cualquier paradigma de programación que quieras nombrar.
candied_orange
2
@ AndrewTFinnell Bueno, cortésmente estaré en desacuerdo. " Uso de revisiones de código para dictar ", no sé de dónde sacaste eso. No me gustaría trabajar en el código con variables i, j, ktodo el lugar después de que el autor original se cierra. No entiendo tu punto sobre el genoma "humano". Dudo que haya un lenguaje en el que haya una sola declaración, o que dos sean demasiado difíciles de comprender. Como he dicho, he visto complejos ify LINQfrases ingeniosas. Se pueden comentar o refactorizar con un nombre semánticamente significativo, supongo que ese es su "buen comentario".
luk32
3
@ luk32 Respeto el derecho a estar en desacuerdo. Las variables de iteración son bastante contextualmente obvias en mi opinión. Si bien entiendo el sentimiento de su declaración, creo que hay demasiadas prácticas que llevan ese sentimiento al extremo. ¿Realmente necesitamos un código que lea: for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)versus for (int i = 0; i < results.length; i++)? Quizás sea una cuestión de preferencia y / o tiempo dedicado a mirar el código. Los nombres excesivamente detallados me huelen.
Andrew T Finnell el
2
No creo que los nombres deban decidirse en las revisiones de código. La revisión del código generalmente debe comenzar después de que el autor piense que es lo suficientemente bueno, lo que también significa que está debidamente comentado, es fácil de entender y las variables tienen nombres decentes. La cuestión es que si los revisores piensan que el código es demasiado complicado o tienen dificultades con el significado de una variable, entonces el código es difícil de entender. Esto no es discutible, evidentemente, al menos un desarrollador, el revisor, no lo entendió. Si necesita o no ser refactorizado (y cómo) o debidamente comentado es un asunto diferente.
Idan Arye
9

La pregunta:

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea? Los que serán relevantes en una revisión por pares pero no se convertirán en una actividad de lista de verificación sin sentido que produzca notas no más útiles que: "Olvidó comentar en la línea 42".

Los comentarios no deben tratar de educar al lector sobre el idioma. Debe suponerse que un lector conoce el idioma mejor que el escritor, pero con mucho menos contexto que el escritor.

Un lector de este código, a partir de su ejemplo, debe saber que exit()saldrá de la aplicación, haciendo que el comentario sea redundante:

/* Exit the application */
exit();

Los comentarios redundantes son una violación de DRY, y los cambios en el código no se propagan necesariamente a los comentarios, dejando comentarios que no reflejan lo que el código está haciendo realmente.

Sin embargo, los comentarios que explican por qué estás haciendo algo pueden ser valiosos, especialmente si no puedes comunicar fácilmente el significado en el código mismo.

PEP 8 de Python (la guía de estilo para Python en la biblioteca estándar de CPython) proporciona la siguiente guía para comentarios en línea:

Use comentarios en línea con moderación.

Un comentario en línea es un comentario en la misma línea que una declaración. Los comentarios en línea deben estar separados por al menos dos espacios de la declaración. Deben comenzar con un # y un solo espacio.

Los comentarios en línea son innecesarios y de hecho distraen si dicen lo obvio. No hagas esto:

x = x + 1                 # Increment x

Pero a veces, esto es útil:

x = x + 1                 # Compensate for border

Dado ese ejemplo, personalmente prefiero ir un paso más allá y trataría de eliminar este comentario también. Por ejemplo, podría llegar a:

border_compensation = 1
compensated_x = x + border_compensation

Hacer que su código se auto documente no es una idea nueva .

De vuelta a la pregunta real:

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea?

Creo que la guía y el ejemplo de PEP 8 demuestran un buen estándar de codificación que captura esta idea. Entonces sí, creo que es posible.

Aaron Hall
fuente
1
"Debe suponerse que un lector conoce el idioma mejor que el escritor" Me cuesta creer que esa sea la actitud correcta. Puedo ver asumiendo que saben tanto , pero cada equipo es diferente y cada persona en un equipo es diferente, por lo que una declaración general sobre este punto en particular no parece sabio.
Bryan Oakley
44
Sin esta guía, los programadores junior enviarán comentarios que explican el código trivial a nadie más que a ellos mismos, y los programadores de nivel medio que usan soluciones incómodas simplemente para hacer que el código sea más accesible para los programadores junior. Esta guía elimina la redundancia y garantiza que incluso un programador competente continúe mejorando su código. Cuando reviso el código yo mismo, es posible que haya olvidado el contexto, pero en general, sé lo que el lenguaje está haciendo aún mejor que cuando lo escribí por primera vez.
Aaron Hall el
4

Creo que cuando ves este tipo de comentarios, y de vez en cuando escribo de esta manera, es porque el autor está escribiendo la especificación en los comentarios y luego revisa e implementa cada comentario.

Si tenemos el desafío de escribir un estándar de codificación que produzca un código que sea comprensible en términos de su funcionalidad requerida en lugar de su funcionalidad real (para que los errores puedan detectarse), entonces ¿estamos realmente hablando de cómo se definen, documentan y vinculan las especificaciones? ¿el producto final?

editar ----

Solo para aclarar. No me estoy metiendo en comentarios vs tdd vs pruebas unitarias que mejor. O sugerir un comentario por línea es bueno / malo

Solo estoy sugiriendo una razón por la que podría ver el estilo de comentario mencionado en el ejemplo.

Y a partir de ese cuestionamiento si un estándar de codificación sobre comentarios realmente se escribiría mejor como un requisito de documento de especificación de algún tipo.

es decir, los comentarios son para explicar el propósito del código, que también es lo que es una especificación

Ewan
fuente
66
En 20 años, nunca he visto a alguien comentar un prototipo de su código de esta manera y luego llenar los vacíos con el código real. Ya hay una forma objetiva de lograr lo que estás diciendo, o lo que creo que estás diciendo. Se llama Test Driven Development. Las pruebas unitarias definen la especificación y si el código se adhiere a esa especificación. Todo sin comentarios.
Andrew T Finnell el
99
Si bien no creo que el código en la pregunta sea un buen ejemplo de esto, la práctica de escribir primero un procedimiento en los comentarios, y luego regresar y completar el código se menciona específicamente en "Código completo" como uno posible práctica para ayudar a producir código legible, @AndrewTFinnell. Definitivamente no es inaudito, incluso si está fuera de su experiencia.
Josh Caswell
66
también es anterior a tdd, creo
Ewan
2
¿Estás hablando del proceso de programación de pseudocódigo? El propósito de eso era reducir los comentarios. Nunca recuerdo ese libro que indica que los comentarios deberían dejarse en el código. Y comentar para producir un procedimiento conceptual está destinado a ser de alto nivel, no de bajo nivel. Si uno comentara cada línea que pretendía escribir, podría haber escrito las líneas. La idea es prototipar los principios del código, no cada línea. El libro no sugiere comentar cada línea. Ese es el enfoque de esta pregunta. Y podría estar equivocado, pero creo que eso está en la Segunda Edición.
Andrew T Finnell el
2
@JoshCaswell & Ewan, sí, era una técnica hace muchos años y de hecho era anterior a TDD. Pero, ¡estabas destinado a eliminar los comentarios después! Y TDD lo ha suplantado por completo como una forma sensata de crear código que cumpla con una especificación.
David Arno
4

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea? Los que serán relevantes en una revisión por pares pero no se convertirán en una actividad de lista de verificación sin sentido que produzca notas no más útiles que: "Olvidó comentar en la línea 42".

Obviamente, esto va más allá de la documentación: toca la forma en que está estructurado el código, qué algoritmos se eligen, etc. Incluso puede tocar el análisis y diseño de requisitos.

Mi regla número 1 es "No documentar lo obvio". La regla # 2 es "Escribir código obvio".

Para el código crítico para la seguridad (en el que nunca he tenido que trabajar, gracias a Dios), este es un primer paso necesario pero nada cercano. Puede que incluso tenga que reducir a exigir qué características del lenguaje deben evitarse (he visto más de un estándar que exige "No usarás scanf( "%s", input ); por ningún motivo ").

John Bode
fuente
Obvio está en el ojo del espectador. Y cambios según la fecha límite.
Tony Ennis
3

La mejor práctica del código autodocumentado no es un consenso general; aunque es ampliamente aceptable que el código fácil de entender sea mejor que el código críptico, no todos están de acuerdo en si el código complicado siempre debe ser refactorizado o si está bien comentar eso.

Pero este debate trata sobre piezas de código que son difíciles de entender, y está hablando de comentar todas y cada una de las líneas de código. Las líneas de código que son difíciles de entender deberían ser muy raras: si la mayoría de sus líneas son complicadas como esta, entonces está usando en exceso frases ingeniosas y debería detenerse. Claro, el papel de una línea puede ser un poco difícil de entender a veces, pero ese es el papel en el contexto de un código más grande: lo que hace la línea en sí es casi siempre sencillo.

Por lo tanto, no debería comentar líneas, debería comentar fragmentos de código. Se pueden colocar comentarios específicos cerca de las líneas a las que se refieren, pero estos comentarios todavía se refieren al código más grande. No describen qué / por qué lo hace la línea; describen lo que hace en ese código y / o por qué es necesario en ese código.

Por lo tanto, no son las líneas las que deben comentarse, sino piezas de código más grandes. ¿Debería comentarse cada fragmento de código? No. Harold Abelson dijo que "los programas deben ser escritos para que la gente los lea, y solo de manera incidental para que las máquinas se ejecuten ". Pero los comentarios son solo para que la gente los lea, la máquina no los ejecuta. Si sus estándares de codificación obligan a escribir comentarios redundantes en cada línea / pieza de código, no solo está cargando al desarrollador que necesita escribirlos, ¡también está cargando a los desarrolladores que tendrán que leerlos !

Esto es un problema, porque cuando la mayoría de los comentarios que lees son redundantes, dejas de prestarles atención (porque sabes que solo serán basura redundante), y luego te perderás los comentarios importantes . Así que digo: escriba solo el comentario importante, para que cuando alguien vea un comentario en el código sepa que vale la pena leerlo para comprender el código.

Idan Arye
fuente
1
Perderse los comentarios importantes: +1. La oración que comienza: "No describen" podría usar alguna reestructuración para que sea más fácil de seguir.
candied_orange
3

En mi humilde opinión, debe hacer ambas cosas. Comentar cada línea es una tontería, porque terminas con líneas como

  i++;    /* Increment i */

sin absolutamente ninguna idea de por qué querrías incrementar i. Extiéndelo un poco y tendrá el típico estilo de comentarios Doxygen, que produce una gran cantidad de palabrería sin proporcionar ninguna idea de para qué sirve el código o cómo funciona. (Al menos por lo que he visto: admito que podría ser posible escribir documentación útil utilizando un sistema como ese, pero no estoy conteniendo la respiración).

OTOH, si escribe un buen bloque de comentarios al comienzo de la función (o cualquier agrupación que sea lógica), describiendo tanto lo que se debe lograr como cómo, si es menos que obvio, tiene algo que es útil. Si eres yo, incluso podrías incluir el código LaTeX para ecuaciones relevantes o referencias a documentos, por ejemplo, "Esto implementa un esquema WENO para resolver ecuaciones de Hamilton-Jacobi, como se discute en ..."

jamesqf
fuente
2
+1 para el comentario de doxygen: esta es precisamente mi objeción para incluir la "documentación" de doxygen en mi código; El 95% del tiempo solo repite lo que ya es obvio de la firma de la función. Yo tampoco he visto una sola documentación de doxygen que valga la pena todavía. Escribir esos comentarios desperdicia tiempo tres veces: una vez para escribir los comentarios, una vez para leerlos nuevamente y otra para depurar los problemas creados por el contenido de comentarios obsoletos.
cmaster
1
¿No te estás contradiciendo? Creo que ambos estaríamos de acuerdo en que es fundamental que una función tenga un comentario que describa lo que hace desde una perspectiva de recuadro negro: "estas entradas entran, la función hace esto y salen estas salidas". Forma el contrato entre la persona que escribió la función y las personas que la utilizan. El propósito de Doxygen es simplemente estandarizar el formato de esos comentarios de manera que se pueda analizar y hacer que se pueda buscar / indexar. Entonces, ¿por qué querrías un "buen bloque de comentarios" pero no lo quieres en un formato estándar legible por humanos y máquinas?
Graham
El uso de un estándar de comentarios como JSDoc, JavaDoc y Doxygen están destinados a proporcionar documentación legible por humanos y de búsqueda, como dijo @Graham. La línea de código mencionada en esta respuesta no tiene nada que ver con Doxygen. Ni siquiera puedo imaginar que exista un conjunto de reglas que analice ese comentario y produzca una entrada en la documentación de salida. Cuando miras los documentos para JMI, las bibliotecas estándar de Java, etc., todos se producen utilizando una herramienta muy similar a Doxygen. Ese es el propósito de eso. No es lo que se dice aquí
Andrew T Finnell el
No estoy inventando esto: para cumplir con un requisito canadiense, una compañía en la que trabajé hizo que los desarrolladores escribieran un preprocesador que agregó comentarios EXACTAMENTE como el ejemplo del OP. Creo que el nuestro fue "C ADD 1 TO I" o algo así. Fue FORTRAN, por lo que los bucles se recomendaron de forma similar "C LOOP FROM 1 TO 10". El código fue CARGADO con comentarios inútiles. Eliminé toda esa basura mientras mantenía el código. Nadie nunca me dijo nada.
Tony Ennis
2

¡Es hora de traer de vuelta los diagramas de flujo! (En realidad no, pero espera un minuto)

El otro día encontré mi vieja plantilla de diagrama de flujo. Solo lo he usado para tareas y bromas (tienes que amar un buen diagrama de flujo tonto). Pero incluso en este momento, la mayoría de los programadores comerciales que todavía usaban diagramas de flujo los generaban automáticamente a partir del código (lo que socava completamente el propósito original del diagrama de flujo, que era ayudar a escribir un mejor código y era bastante útil en el código de máquina). Sin embargo, con los lenguajes de nivel superior, el diagrama de flujo cambió de ser una muleta a un hoble. ¿Por qué? La abstracción del diagrama de flujo era la misma que el código. Los comentarios mostrados son un obstáculo en el sentido de que están en el mismo nivel de abstracción que el código. Los buenos comentarios tienen un nivel diferente de abstracción que el código. La forma más fácil de hacerlo es usar comentarios de por qué mientras el código maneja qué.

hildred
fuente
Lamento informarle que los diagramas de flujo nunca desaparecieron.
Ant P
Los buenos comentarios tienen un nivel de abstracción diferente al del código . ¡Escucha Escucha!
candied_orange
1
Si bien este podría ser un consejo decente, no parece abordar la pregunta que se hizo, excepto quizás una sola oración.
Bryan Oakley el
0

Contestaré la pregunta como se indica:

Dado todo esto, ¿es posible incluso escribir buenos estándares de codificación que capturen esta idea?

Si. WYSIWYG. Un buen estándar de codificación es literalmente " es claro para el lector lo que hace el siguiente código y por qué ".

En otras palabras, mis comentarios de revisión de código sobre la legibilidad del código literalmente, 1-1, surgen de mi estado mental de

Yo, como lector, (mejor aún, como estándar mínimo, un modelo mental de un lector menos experimentado pero razonable), no entendería el propósito o método de trabajo del siguiente código

En general, las personas son fáciles de abordar "esto necesita más legibilidad" cuando escuchan "Yo, como desarrollador senior al que espero respetes por no ser tonto, al principio no entendí este código o por qué está allí o qué es. lo hace, por lo que debe explicarse ".

Esto cambia el discurso de "no seguiste el estándar sin sentido" a "tu código tiene una deficiencia específica de legibilidad que conduce a un problema práctico ".

Un segundo estándar que debe hacerse explícito es la "prueba de emergencia de las 2 a. M.".

¿Puede su copia de seguridad, que no tiene experiencia con este código, averiguar cuál es el problema con el código al depurarlo durante la llamada de emergencia del puente de producción a las 2 am, cuando está de vacaciones en los Andes chilenos sin teléfono celular?

Esto puede sonar subjetivo, pero en realidad es fácil de medir en la práctica: llame a un miembro del equipo junior al azar que se esperaría que se depurara por la noche en una emergencia de producción, y pídales que expliquen cómo funciona el código particular sin comentarios y por qué es ahí.

DVK
fuente
0

Esta respuesta cubrió la mayoría de los problemas, sin embargo, hay una cosa importante.

Me gustaría capturar una idea en la línea de: considere un comentario para cada línea, secuencia, declaración, sección, estructura, función, método, clase, paquete, componente, ... de código.

Existen herramientas para generar documentación a partir de código, como por ejemplo doxygen. Si usa tales herramientas, entonces tiene sentido comentar archivos, funciones, clases, etc. Incluso si el nombre de la función se explica por sí mismo, todavía lo estoy haciendo por coherencia, porque las personas que lean la documentación estarán agradecidas.

BЈовић
fuente
1
Pero la "documentación" generada por tales herramientas es, al menos en mi experiencia, generalmente vale menos que ninguna documentación, porque no proporciona al usuario información útil (y hace que pierdan el tiempo tratando de extraer el información existente), pero engaña a los desarrolladores para que piensen que están documentados correctamente su código.
jamesqf
@jamesqf Sí, cuando la mitad de las funciones no están documentadas y la otra mitad mal. Sin embargo doxygen puede generar bastante buena documentación, suponiendo que los desarrolladores adecuadamente comentado sus funciones, clases, etc
BЈовић
-1

Muchas de las respuestas existentes están bien detalladas, pero me pareció importante responder:

... [comentarios] que serán relevantes en una revisión por pares pero que no se convertirán en una actividad de lista de verificación sin sentido ...

Para mí, los únicos comentarios que podrían ser un estándar se pueden responder preguntando qué comentarios se notan cuando faltan . En otras palabras: comentarios utilizados por IDEs o software de documentación.

Dicho esto, esto es subjetivo a las herramientas que usan los desarrolladores, y no todos los comentarios utilizados por dicho software son tan útiles entre sí .

Erdrik Ironrose
fuente