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
fuente
/* Display an error message */comentarios son horribles y en realidad impactan la legibilidad.Respuestas:
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í:
Obviamente, puede escribir una lista de verificación para sus revisiones de código , que contiene preguntas como
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.
fuente
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 chairsNo 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
fuente
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.
fuente
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.
fuente
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.Actualizar
Mi respuesta entre comillas para enfatizar:
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.
fuente
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
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.
fuente
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.
fuente
x,y, yz, oi,jykpueden 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.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:
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)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.
fuente
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 complejosifyLINQfrases ingeniosas. Se pueden comentar o refactorizar con un nombre semánticamente significativo, supongo que ese es su "buen comentario".for (int indexForCurrentDatabaseRow = 0; indexForCurrentDatabaseRow < currentUserRecordSetResults.length; indexForCurrentDatabaseRow = indexForCurrentDatabaseRow + 1)versusfor (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.La pregunta:
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: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:
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:
Hacer que su código se auto documente no es una idea nueva .
De vuelta a la pregunta real:
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.
fuente
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
fuente
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 ").fuente
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.
fuente
En mi humilde opinión, debe hacer ambas cosas. Comentar cada línea es una tontería, porque terminas con líneas como
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 ..."
fuente
¡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é.
fuente
Contestaré la pregunta como se indica:
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
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.".
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í.
fuente
Esta respuesta cubrió la mayoría de los problemas, sin embargo, hay una cosa importante.
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.
fuente
Muchas de las respuestas existentes están bien detalladas, pero me pareció importante responder:
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í .
fuente