El desarrollador principal de nuestra tienda insiste en que cada vez que se modifica el código, el programador responsable debe agregar un comentario en línea que indique lo que hizo. Estos comentarios generalmente se ven como// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

Usamos TFS para el control de revisiones, y me parece que los comentarios de este tipo son mucho más apropiados como notas de registro que como ruido en línea. TFS incluso le permite asociar un registro con uno o más errores. Parece que algunos de nuestros archivos de clase más antiguos, a menudo modificados, tienen una relación de comentario a LOC cercana a 1: 1. A mis ojos, estos comentarios hacen que el código sea más difícil de leer y agregan valor cero.

¿Es esta una práctica estándar (o al menos común) en otras tiendas?

Por lo general, considero que tales comentarios son una mala práctica y creo que este tipo de información pertenece a los registros de confirmación de SCM. Simplemente hace que el código sea más difícil de leer en la mayoría de los casos.

Sin embargo , todavía a menudo hago algo como esto para tipos específicos de ediciones.

Caso 1 - Tareas

Si usa un IDE como Eclipse, Netbeans, Visual Studio (o tiene alguna forma de realizar búsquedas de texto en su base de código con cualquier otra cosa), tal vez su equipo use algunas "etiquetas de comentarios" o "etiquetas de tareas" específicas. En cuyo caso esto puede ser útil.

De vez en cuando, al revisar el código, agrego algo como lo siguiente:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

o:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

Utilizo diferentes etiquetas de tareas personalizadas que puedo ver en Eclipse en la vista de tareas para esto, porque tener algo en los registros de confirmación es algo bueno pero no suficiente cuando un ejecutivo le pregunta en una reunión de revisión por qué se olvidó por completo la corrección de errores XY y se deslizó a través. Entonces, en asuntos urgentes o piezas de código realmente cuestionables, esto sirve como un recordatorio adicional (pero generalmente mantendré el comentario breve y revisaré los registros de confirmación porque ESO es para eso que está el recordatorio, así que no abarroto el código también mucho).

Caso 2 - Parches de Libs de terceros

Si mi producto necesita empaquetar un código de terceros como fuente (o biblioteca, pero reconstruido desde la fuente) porque necesitaba ser parcheado por alguna razón, documentamos el parche en un documento separado donde enumeramos esas "advertencias" para referencia futura, y el código fuente generalmente contendrá un comentario similar a:

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

Caso 3 - Soluciones no obvias

Este es un poco más controvertido y más cercano a lo que pide su desarrollador senior.

En el producto en el que trabajo en este momento, a veces (definitivamente no es algo común) tenemos un comentario como:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

Solo hacemos esto si la corrección de errores no es obvia y el código se lee de manera anormal. Este puede ser el caso de las peculiaridades del navegador, por ejemplo, o las oscuras correcciones de CSS que debe implementar solo porque hay un error de documento en un producto. Entonces, en general, lo vincularíamos a nuestro repositorio de problemas internos, que luego contendrá el razonamiento detallado detrás de la corrección de errores y los punteros a la documentación del error del producto externo (por ejemplo, un aviso de seguridad para un defecto bien conocido de Internet Explorer 6, o algo como eso).

Pero como se mencionó, es bastante raro. Y gracias a las etiquetas de tareas, podemos ejecutarlas regularmente y verificar si estas soluciones extrañas aún tienen sentido o pueden eliminarse gradualmente (por ejemplo, si dejamos de admitir el producto defectuoso que causa el error en primer lugar).

Esto solo en: un ejemplo de la vida real

En algunos casos, es mejor que nada :)

Acabo de encontrar una gran clase de cálculo estadístico en mi base de código, donde el comentario del encabezado tenía la forma de un registro de cambios con el yadda yadda habitual: revisor, fecha, ID de error.

Al principio pensé en eliminarlo, pero noté que las ID de errores no solo no coincidían con la convención de nuestro rastreador de problemas actual, sino que tampoco coincidían con el del rastreador utilizado antes de unirme a la empresa. Así que traté de leer el código y entender lo que estaba haciendo la clase (no ser estadístico) y también traté de desenterrar estos informes de defectos. Resulta que eran bastante importantes y habrían cambiado la vida del próximo tipo para editar el archivo sin saber sobre ellos bastante horrible, ya que se trataba de problemas menores de precisión y casos especiales basados ​​en requisitos muy específicos emitidos por el cliente de origen en ese momento. . En pocas palabras, si estos no hubieran estado allí, no lo habría sabido. Si no hubieran estado allí Y yo hubiera tenido una mejor comprensión de la clase,

A veces es difícil hacer un seguimiento de requisitos muy antiguos como estos. Al final, lo que hice fue eliminar el encabezado, pero después de introducir un comentario en bloque antes de cada función incriminatoria que describe por qué estos cálculos "extraños" son solicitudes específicas.

Entonces, en ese caso, todavía consideraba que esto era una mala práctica, ¡pero estaba feliz de que el desarrollador original al menos los pusiera! Hubiera sido mejor comentar el código claramente en su lugar, pero supongo que fue mejor que nada.

Utilizamos esa práctica para archivos que no están bajo control de versiones. Tenemos programas RPG que se ejecutan en un mainframe, y ha resultado difícil hacer mucho más que respaldarlos.

Para el código fuente versionado, usamos las notas de check-in. Creo que ahí es donde pertenecen, no abarrotando el código. Son metadatos, después de todo.

Solíamos tener esta práctica hace mucho tiempo en una tienda SW donde nuestro gerente insistía en que quería poder leer los archivos de código en papel y seguir su historial de revisiones. No hace falta decir que no recuerdo ninguna ocasión concreta en la que él haya mirado una copia impresa del archivo fuente: - /

Afortunadamente, mis gerentes desde entonces tienen más conocimiento sobre lo que pueden hacer los sistemas de control de versiones (tengo que agregar que usamos SourceSafe en esa primera tienda). Por lo tanto, no agrego metadatos de versiones al código.

Por lo general, no es necesario si su SCM e IDE le permiten usar la función "mostrar anotación" (llamada de todos modos en Eclipse), puede ver fácilmente qué commit (s) cambió un fragmento de código, y los comentarios de commit deberían indicar quién y por qué.

La única vez que pondría un comentario como este en el código es si es un código particularmente extraño que puede causar confusión a alguien en el futuro, comentaré brevemente con el número de error para que puedan ir al informe de errores y leer en detalle al respecto.

Obviamente, se garantiza que tales comentarios serán incorrectos con el tiempo; si edita una línea dos veces, ¿agrega dos comentarios? ¿A dónde van? Por lo tanto, un mejor proceso es confiar en sus herramientas.

Esta es una señal de que, por cualquier razón, el desarrollador senior no puede confiar en el nuevo proceso para realizar un seguimiento de los cambios y conectar los cambios al sistema de seguimiento de problemas. Debe abordar esta molestia para resolver el conflicto.

Debes entender por qué no puede confiar en eso. ¿Son viejos hábitos? ¿Una mala experiencia con el sistema SCM? ¿Un formato de presentación que no funciona para él? Tal vez ni siquiera sabe sobre herramientas como 'git blame' y la vista de línea de tiempo de Perforce (que esencialmente muestra esto, aunque podría no mostrar qué problema provocó el cambio).

Sin entender su razón para el requisito, no podrá convencerlo.

Trabajo en un producto Windows de más de 20 años. Tenemos una práctica similar que existe desde hace mucho tiempo. No puedo contar la cantidad de veces que esta práctica me ha salvado el tocino.

Estoy de acuerdo en que algunas cosas son redundantes. Solía ​​ser que los desarrolladores usaban esta práctica para comentar el código. Cuando reviso esto, les digo que continúen y eliminen el código, y el comentario no es necesario.

Pero, en muchas ocasiones, puedes ver el código que ha estado alrededor de una década y modificado por 20 desarrolladores, pero nunca refactorizado. Todos hace mucho tiempo olvidaron todos los detalles de los requisitos que estaban en el código original, sin importar todos los cambios, y no hay documentación confiable.

Un comentario con un número de defecto me da un lugar para buscar el origen del código.

Entonces, sí, el sistema SCM hace mucho, pero no todo. Trátelos como lo haría con cualquier otro comentario y agréguelos siempre que se realice un cambio significativo. El desarrollador que mira tu código hace más de 5 años desde cómo te lo agradecerá

Mencionar cada cambio en los comentarios no tiene sentido si tiene un VCS. Mencionar un error específico u otra nota importante relacionada con una línea específica es útil. Un cambio puede incluir muchas líneas alteradas, todas bajo el mismo mensaje de confirmación.

No es que pueda decirlo.

Salpicando TODOs en mi código a medida que avanzo, y el objetivo es eliminarlos antes del tiempo de revisión.