Mantenimiento del código: ¿Para agregar comentarios en el código o simplemente dejarlo al control de versiones?

42

Se nos ha pedido que agreguemos comentarios con etiquetas de inicio, etiquetas finales, descripción, solución, etc. para cada cambio que realicemos en el código como parte de la corrección de un error / implementación de un CR.

Mi preocupación es, ¿esto proporciona algún valor agregado? Tal como están las cosas, tenemos todos los detalles en el historial de control de versiones, que nos ayudarán a rastrear cada cambio.

Pero mis clientes potenciales insisten en tener los comentarios como una "buena" práctica de programación. Uno de sus argumentos es cuando un CR tiene que ser eliminado / cambiado, sería engorroso si no hay comentarios.

Teniendo en cuenta que los cambios serían en gran medida entre el código, ¿realmente ayudaría agregar comentarios para cada cambio que realicemos? ¿No deberíamos dejarlo al control de versiones?

Chillax
fuente

Respuestas:

43

Tienes toda la razón. El seguimiento de los cambios es el trabajo para su sistema de control de versiones. Cada vez que realice una confirmación, debe escribir un mensaje de confirmación explicando lo que se hizo y haciendo referencia a su sistema de seguimiento de errores si se trata de una corrección de errores. Poner un comentario en el código que dice

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

cada vez que arregle un error, su código se volverá ilegible e imposible de mantener rápidamente. También dará como resultado la duplicación de la misma información en dos lugares, lo que empeorará aún más el problema.

Los comentarios no deben usarse para el seguimiento de errores y tampoco deben describir lo que está haciendo su código. Deben explicar por qué estás haciendo X, o por qué estás haciendo X de esta manera particular. Si siente la necesidad de escribir un comentario explicando qué está haciendo un bloque de código, es un olor a código que indica que debe refactorizar este bloque en una función con un nombre descriptivo.

Entonces en lugar de

// fixed bug XXXXX on 10/9/2012

podrías tener un comentario que diga

// doing X, because otherwise Y will break.

o

// doing X, because doing Y is 10 times slower.
Dima
fuente
12
+1 para el código de olor de comentarios que explican "qué". Es bueno ver una respuesta de que los comentarios de código no son un beneficio automático en el sentido de que más comentarios> menos comentarios. Incluso podría retroceder un nivel y pensar que hay casos en los que incluso los comentarios que describen "por qué" podrían ser un olor que indica que el código no está claro. Por ejemplo, si puedo inyectar un BubbleSorter o un QuickSorter, el comentario "Estoy usando QuickSorter porque es más rápido" es superfluo de la misma manera que "inyectar un quicksorter" es superfluo. YMMV.
Erik Dietrich
53

Use la mejor herramienta para el trabajo. Su sistema de control de versiones debe ser la mejor herramienta para registrar cuando se realizan correcciones de errores y CR: registra automáticamente la fecha y quién realizó el cambio; nunca olvida agregar un mensaje (si lo configuró para requerir mensajes de confirmación); nunca anota la línea de código incorrecta ni elimina accidentalmente un comentario. Y si su sistema de control de versiones ya está haciendo un mejor trabajo que sus comentarios, es una tontería duplicar el trabajo agregando comentarios.

La legibilidad del código fuente es primordial. Una base de código repleta de comentarios que brinden el historial completo de cada corrección de errores y CR realizados no será muy legible.

Pero no omita los comentarios por completo: los buenos comentarios (que no documentan servilmente cada inicio / parada / descripción / solución de cada corrección de errores y CR) mejoran la legibilidad del código. Por ejemplo, para un código difícil o poco claro que agregue para corregir un error, // fix ISSUE#413una excelente idea es un comentario del formulario que le dice a las personas dónde encontrar más información en su rastreador de problemas.

Josh Kelley
fuente
29
Estoy de acuerdo, excepto por una cosa: fix ISSUE#413no es un buen comentario en el código. Debe poder entender el código sin tener que consultar documentación externa. En lugar de dar un número aleatorio, explique por qué esta parte del código es necesaria para hacer qué. Para eso están los comentarios: para explicar aquellas partes del código que no son obvias.
meter el
12
@poke - Gracias por señalar eso. Supongo que debo agregar que el único lugar donde uso los comentarios del formulario fix ISSUE#413es donde el problema es tan complicado (un caso de esquina extremadamente dependiente del sistema operativo y de la configuración, o solo desencadenado por datos particulares de clientes malos) que describirlo adecuadamente tomaría un par de párrafos; ese tipo de cosas se maneja mejor con un rastreador de problemas, IMO. Incluso entonces, algún tipo de breve descripción es buena.
Josh Kelley
8
@poke: Diría que un comentario que comienza fix ISSUE#413 está perfectamente bien, e incluso es preferible, siempre y cuando también proporcione una cantidad razonable de información sobre el problema # 413. Simplemente resumir el informe del problema sin proporcionar un puntero hace que la vida sea más difícil para un futuro lector que necesita todos los detalles.
Keith Thompson el
Estoy de acuerdo con poke: nunca debería tener que consultar una fuente externa para comprender el código. Si estoy revisando un cambio, se rompe el flujo. Tengo que ir al rastreador de problemas, extraer el problema y leer todo al respecto. ¿Y qué sucede si cambias los rastreadores de problemas? Puede estar bien tenerlo fix ISSUE#413en el comentario para completarlo, pero no lo use como una muleta.
Michael Dean
"nunca olvida agregar un mensaje (si lo configuró para que requiera mensajes de confirmación); nunca anota la línea de código incorrecta ni elimina accidentalmente un comentario". Acabamos de tratar con SVN que se corrompe a sí mismo y que tiene que restaurar desde la copia de seguridad. Pudimos encontrar el código que aún no había hecho una copia de seguridad, pero cuando volvimos a confirmar los cambios, varias confirmaciones separadas se convirtieron en una. Mi punto es que nunca es una palabra demasiado fuerte, y no olvidemos que las personas se mueven al nuevo software VCS, y traer el historial de revisión podría no ser factible o posible.
Andy
7

Los comentarios en el código son acerca de lo que el código es en ese momento. Tomar una instantánea en un momento dado no debería referirse a versiones antiguas (o peor, futuras) del código.

Los comentarios en VCS son sobre cómo ha cambiado el código. Deberían leer como una historia sobre el desarrollo.

Ahora, cada cambio debe incluir comentarios? En la mayoría de los casos, sí. La única excepción que imagino es cuando el comportamiento esperado ya estaba documentado pero no era lo que obtuviste, debido a un error. Solucionarlo hace que los comentarios existentes sean más precisos, por lo que no es necesario cambiarlos. El error en sí mismo debe documentarse en el historial del ticket y en el comentario de confirmación, pero solo en el código si el código parece extraño. En ese caso, a // make sure <bad thing> doesn't happendebería ser suficiente.

Javier
fuente
8
Votaría esto, pero realmente no puedo estar de acuerdo con "¿cada cambio debe incluir comentarios? En la mayoría de los casos, sí". Un comentario de check-in / commit, sí, absolutamente. Comentarios de código, definitivamente no necesariamente.
un CVn el
6

Un tipo de comentario que realmente aprecio es:

// Esto se implementó para la Regla de negocios 5 de la Propuesta 2

o lo que sea que uses para reunir tus requisitos.

Esto tiene dos ventajas, una es que le permite encontrar la razón por la que implementó un algoritmo determinado sin buscar y otra es que lo ayudará a comunicarse con ingenieros que no son de software que trabajan / crean los documentos de requisitos.

Es posible que esto no ayude con equipos más pequeños, pero si tiene analistas que desarrollan sus requisitos, puede ser invaluable.

Bill K
fuente
2
Sin embargo, eso es diferente porque proporciona una trazabilidad ortogonal al control de versiones: la conexión entre el código y la especificación de requisitos que implementa.
Kaz
En un sistema donde el control de versiones se combina con el sistema de errores / requisitos, se proporciona una trazabilidad completa sin necesidad de comentarios. A veces es útil trabajar de otra manera. Dado un archivo de SCM, muéstreme qué requisitos se implementaron cuando. O, dado un requisito, muéstrame todos los archivos modificados para implementarlo.
Activo el
4

Sus clientes potenciales tienen razón cuando dicen que los comentarios son una buena práctica de programación, sin embargo, hay excepciones. Agregar un comentario para cada cambio que realice es uno de ellos. Y tiene razón al decir que esto debería pertenecer al sistema de control de versiones. Si tiene que mantener estos comentarios en un solo lugar, entonces el VCS es el camino a seguir. Los comentarios en el código fuente tienden a envejecer y no mantenerse. Ningún comentario es mucho mejor que los malos comentarios. Lo que no desea es tener comentarios en ambos lugares (en el código y VCS) que no estén sincronizados. El objetivo es mantener las cosas SECAS al tener una sola fuente de verdad para los cambios en el código.

marco-fiset
fuente
3

Además de lo que otros han dicho, considere lo que sucede si un cambio tiene efectos dominó en todo el sistema. Supongamos que refactoriza una parte de una interfaz central en el proceso de implementación de una solicitud de cambio; ese tipo de cambio puede tocar fácilmente un gran porcentaje de los archivos de código fuente en cualquier pieza de software no trivial con lo que equivale a cambios triviales (clase o cambios de nombre del método). ¿Se supone que debe revisar cada archivo tocado por dicha operación para anotarlo manualmente con dichos comentarios, en lugar de confiar en que el VCS lo haga todo automáticamente? En un caso, está buscando un trabajo de poco más de cinco minutos con cualquier herramienta de refactorización decente seguida de una recompilación para asegurarse de que nada rompa la construcción, mientras que el otro puede pasar fácilmente al trabajo de un día. ¿Para qué beneficio específico?

También considere lo que sucede cuando mueve partes del código. Uno de los desarrolladores de bases de datos con los que trabajo está en el campo de "cada línea de SQL debe anotarse con la revisión en la que se modificó, y vamos a hacer historiales de revisión separados para cada archivo porque entonces es más fácil de ver quién cambió qué, cuándo y por qué ". Eso funciona bastante bien cuando el cambio esen el orden de cambiar líneas simples. No funciona tan bien cuando, como hice recientemente para solucionar un problema de rendimiento grave, divide partes de una consulta más grande introduciendo tablas temporales, luego cambia el orden de algunas de las consultas para que se adapten mejor al nuevo flujo de código. Por supuesto, la diferencia con respecto a la versión anterior carecía en gran medida de sentido, ya que decía que habían cambiado alrededor de dos tercios del archivo, pero el comentario de verificación también era algo así como "una importante reorganización para solucionar problemas de rendimiento". En el momento en que miró manualmente las dos versiones, estaba bastante claro que las partes grandes realmente eran iguales, solo se movían. (Y tomó el procedimiento almacenado en cuestión de tomar regularmente más de medio minuto para ejecutar, a unos pocos segundos. En ese momento,

Con muy pocas excepciones, el seguimiento de cambios y la referencia de problemas es el trabajo de VCS, IMNSHO.

un CVn
fuente
3

Por lo general, sigo esta regla: si el cambio es obvio y el código resultante no genera preguntas, no revierte ni cambia sustancialmente ningún comportamiento anterior de una manera sustancial, entonces deje que el VCS rastree los números de error y otra información de cambio.

Sin embargo, si hay un cambio que no es obvio, que cambia la lógica, especialmente cambia sustancialmente la lógica realizada por otra persona de una manera no obvia, puede ser muy beneficioso agregar algo como "este cambio es hacer esto y eso debido al error # 42742 ". De esta manera, cuando alguien mira el código y se pregunta "¿por qué está esto aquí? Esto se ve raro", tiene algo de orientación frente a él y no tiene que investigar a través de VCS. Esto también evita situaciones en las que las personas rompen los cambios de otros porque están familiarizados con el estado anterior del código pero no notan que se ha cambiado desde entonces.

StasM
fuente
2

Los comentarios relacionados con el control de versiones no pertenecen al archivo fuente. Solo agregan desorden. Como es probable que se requiera colocarlos en el mismo lugar (como un bloque de comentarios en la parte superior del archivo), causarán conflictos molestos de solo comentarios cuando se fusionen ramas paralelas.

Cualquier información de seguimiento que pueda extraerse del control de versiones no debe duplicarse en el cuerpo del código. Eso se aplica a ideas tontas como las palabras clave de pago de RCS como $Log$y sus gustos.

Si el código viaja fuera del alcance del sistema de control de versiones, ese rastro de comentarios sobre su historial pierde contexto y, por lo tanto, la mayor parte de su valor. Para comprender correctamente la descripción del cambio, necesitamos acceso a la revisión, para que podamos ver la diferencia de la versión anterior.

Algunos archivos antiguos en el kernel de Linux tienen grandes bloques de comentarios históricos. Esos datan de cuando no había un sistema de control de versiones, solo tarballs y parches.

Kaz
fuente
2

Los comentarios en el código deben ser mínimos y precisos. Agregar información de defecto / cambio no es valioso. Debe usar el control de versiones para ello. En algún momento, el control de versiones proporciona una forma ligeramente mejor de cambio: utilizamos ClearCase UCM; Las actividades de UCM se crean en base a números de defectos, área de cambio, etc. (por ejemplo, defect29844_change_sql_to_handle_null).

Se prefieren los comentarios detallados en los comentarios de check-in.

Prefiero incluir proporcionar detalles sobre la información de fondo, detalles de la solución NO implementada debido a algunos efectos secundarios.

Pramagic Programmer y CleanCode llevan a la siguiente guía

Mantenga el conocimiento de bajo nivel en el código, dónde pertenece, y reserve los comentarios para otras explicaciones de alto nivel.

Jayan
fuente