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

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?

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.

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.

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.

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.

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.

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.

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.

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.

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.