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

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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 ").

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.

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 ..."

¡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é.

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í.

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.

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í .