Mantenimiento del código: ¿Para agregar comentarios en el código o simplemente dejarlo en el 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 que explique lo que se hizo y hacer referencia a su sistema de seguimiento de errores si se trata de una corrección de errores. Poniendo 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 solucione un error, su código se volverá ilegible e inalcanzable. También resultará en la duplicación de la misma información en dos lugares, lo que hará que el desastre sea aún peor.

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

Así que en lugar de

// fixed bug XXXXX on 10/9/2012

puede que tengas 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 versión debería ser la mejor herramienta para registrar cuando se hacen correcciones de errores y CR: registra automáticamente la fecha y quién hizo el cambio nunca olvida agregar un mensaje (si lo has configurado para requerir mensajes de confirmación); nunca anota la línea de código incorrecta o borra 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 que esté repleta de comentarios que den el historial completo de todas las correcciones de errores y CR hechos no será muy legible en absoluto.

Pero no omita los comentarios por completo: Bien los comentarios (no documentando 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 poco de código complicado o poco claro que agregas para corregir un error, un comentario del formulario // fix ISSUE#413 que le indica a la gente dónde encontrar más información en tu rastreador de problemas es una excelente idea.

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

Los comentarios en VCS se refieren a cómo ha cambiado el código. Deben 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 recibiste, debido a un error. Repararlo hace que los comentarios existentes sean más precisos, por lo que no es necesario cambiarlos. El error en sí debe documentarse en el historial de tickets y en el comentario de confirmación, pero solo en el código si el código parece extraño. En ese caso, un // make sure <bad thing> doesn't happen debería ser suficiente.

Un tipo de comentario que realmente aprecio es:

// Esto implementado 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 y que trabajan en / crean los documentos de requisitos.

Esto puede no ayudar 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 por 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 se mantienen. No hay comentarios son mucho mejores que 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 en SECO al tener una única 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 dominantes en todo el sistema. Digamos 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 de método). ¿Se supone que debe revisar cada uno de los archivos tocados por tal 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ás buscando un poco más de un trabajo de cinco minutos con cualquier herramienta de refactorización decente seguida de una recompilación para asegurarte de que nada rompió la construcción, mientras que el otro puede fácilmente inflarse en el trabajo de un día. ¿Para qué beneficio específico?

También considera lo que sucede cuando mueves partes del código. Uno de los desarrolladores de bases de datos con los que trabajo está en el campo de gran parte "cada línea de SQL se debe anotar 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 es en el orden de cambio de líneas individuales. No funciona tan bien cuando, como lo hice recientemente para solucionar un problema grave de rendimiento, se dividen partes de una consulta más grande introduciendo tablas temporales, y luego se modifica el orden de algunas de las consultas para que se ajuste mejor al nuevo flujo de código. Por supuesto, la diferencia con respecto a la versión anterior no tenía sentido en gran medida, ya que decía que dos tercios del archivo habían cambiado, pero el comentario de verificación también era algo así como "reorganización importante para solucionar problemas de rendimiento". En el momento en que miraste manualmente las dos versiones, estaba bastante claro que las partes grandes realmente eran iguales, solo se movían. (Y el procedimiento almacenado en cuestión tardó en ejecutarse durante más de medio minuto, a unos pocos segundos. En ese momento, estaba en gran parte vinculado a E / S con pocos lugares para una mejora adicional significativa, al menos en el corto plazo. )

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

Por lo general, sigo esta regla: si el cambio es obvio y el código resultante no genera preguntas, no revierte o cambia sustancialmente cualquier comportamiento anterior de manera sustancial, entonces deje que el VCS realice un seguimiento de los números de error y otros cambios. información.

Sin embargo, si hay un cambio que no es obvio, que cambia la lógica, en especial cambia sustancialmente la lógica realizada por otra persona de una manera no obvia, puede ser muy beneficioso agregar algo como "este cambio es para hacer esto y aquello debido a un error # 42742 ". De esta manera, cuando alguien mira el código y se pregunta "¿por qué está esto aquí? Esto parece extraño", tiene cierta orientación frente a él y no tiene que hacer una investigación 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 versión no pertenecen al archivo fuente. Sólo añaden desorden. Como es probable que deban colocarse en el mismo lugar (como un bloque de comentarios en la parte superior del archivo), causarán conflictos de molestias de solo comentarios cuando las ramas paralelas se combinen.

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 su tipo.

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 poder ver la diferencia de la versión anterior.

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

Los comentarios en el código deben ser mínimos y precisos. Adición de información de defecto / cambio no es valiosa. Usted debe utilizar el control de versiones para ello. En algún momento, el control de versiones proporciona una forma de cambio ligeramente mejor: usamos ClearCase UCM; Las actividades de UCM se crean en función de los números de defecto, área de cambio, etc. (por ejemplo, defect29844_change_sql_to_handle_null).

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

Prefiero incluir información sobre antecedentes, detalles de la solución que NO se implementó 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, donde pertenece, y reserve los comentarios para otras explicaciones de alto nivel.