¿Es generalmente útil incluir problemas de JIRA en los comentarios de código?

8

De vez en cuando, dejo comentarios como

# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.

o 

# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.

Mi principal preocupación al hacerlo es que aumenta nuestra dependencia de JIRA, por lo que esos comentarios serían totalmente discutibles si tuviéramos que migrar a otro sistema de gestión de proyectos. Si bien no preveo que eso suceda en el futuro cercano, sigo desconfiando del mayor acoplamiento de los componentes de la organización (en este caso: código, repositorios de código y un sistema de gestión de proyectos).

Sin embargo , sí veo el beneficio de tener referencias a decisiones de diseño documentadas y presentar inspiración en toda la base del código. Por lo que puedo decir, los beneficios son

  1. un camino claro para tomar decisiones de diseño, que ayuda a depurar y acelerar segmentos particulares de código desconocido,
  2. menos comentarios de varias líneas, lo que hace que el código parezca más limpio / menos intimidante para los nuevos contribuyentes,
  3. un camino claro para (potencialmente) interesados ​​técnicos y no técnicos actuales, y
  4. una disminución en el número de preguntas "por qué es esto aquí" debido a lo mencionado anteriormente.
project-management coding-style communication comments jira Mr_Spock
fuente
duplicado bastante evidente de ¿Es una buena práctica comentar con el número de problema?
mosquito
2
@gnat No fue "descarado", pero gracias por la referencia.
Mr_Spock
1
Una pequeña ventaja es que herramientas como los IDE pueden crear fácilmente hipervínculos al ticket correspondiente.
axd

Respuestas:

7

Trataría de evitar tales comentarios. Aunque creo que hay un lugar para ellos donde tienes un requisito particularmente molesto. Sin lo cual, cualquiera podría querer refactorizar el código. p.ej.

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

o de manera similar podrías poner un enlace

//work around stolen from this stackoverflow answer http://stackoverflow....

Pero no por las razones por las que declaras un mayor acoplamiento. De hecho, nombro todas mis ramas de características después del boleto para el que están destinadas. Por lo tanto, es posible rastrear todo el trabajo hasta un ticket si es necesario, a través del historial de confirmación. (también puede hacer algunas cosas inteligentes de cierre automático si se siente inteligente)

No, no me preocupa cambiar el sistema de tickets. Pero de lo que me he dado cuenta es que es muy raro que alguien mire hacia atrás las entradas una vez que hayan terminado.

Entonces el comentario es útil porque le dice a su futuro reemplazo:

"No, no me he equivocado, alguien me dijo que tenía que ser así. ¡Mira! ¡Aquí está el número de boleto para probarlo!"

Pero no van a ir a revisar ese boleto. La vida es demasiado corta.

Si tiene la costumbre de poner comentarios de referencia de tickets en todas partes, entonces pierden su impacto. En lugar de ser una bandera "¡lee esto, es súper importante!" simplemente se vuelven desordenados.

En general, los requisitos deben registrarse a través del medio de pruebas. Si las pruebas pasaron, entonces se deben cumplir los requisitos, no tenemos que preocuparnos por cómo se declararon originalmente.

Ewan
fuente
1
Estoy de acuerdo. Hay veces que he buscado en la base de datos de rastreo hacia atrás, pero no con frecuencia. Prefiero tener la información relevante en los comentarios del código solo para que esté en un solo lugar, por lo que no estoy a favor de poner números de boletos para boletos trabajados. Por otro lado, he adquirido la costumbre de dejar números de boletos próximos / futuros en TODO que podría estar dejando en el código actual, ya que da una idea de cuándo se resolverá TODO y si alguien viene más tarde y encuentra el TODO para un boleto que ya está cerrado, es una bandera que se perdió cuando funcionó el boleto futuro.
jia103
5

Para los comentarios de código, hay muy poca utilidad. Para los comentarios de control de versiones, son muy útiles por los motivos que se detallan a continuación.

Los comentarios de código realmente deberían usarse para ayudar a comprender la intención de las cosas complicadas.

Malos tipos de comentarios de código:

  • Updated EHS 10/24/2015 - si quisiera saber eso, usaría el control de versiones para encontrar quién escribió qué líneas.
  • For spec 0.4 - eso puede ser parte de los comentarios de confirmación, pero no me ayuda a comprender mejor el código
  • Otras variaciones del mismo tipo de cosas.

Si existen comentarios de código, deberían ayudar a comprender cómo se relaciona el bloque de código con el dominio comercial.

Si JIRA y su control de versión están vinculados, entonces sí tienen sentido para los mensajes de confirmación .

  • Hacer referencia al ticket proporciona la trazabilidad de los cambios necesarios para el trabajo solicitado
  • JIRA no es la única herramienta de seguimiento de tickets capaz de esta sincronización.

Recomiendo un formato de comentario como el siguiente:

 DIGIT-827: We only need to use the following for V4 of the computation.

JIRA y casi cualquier herramienta con esta integración es lo suficientemente inteligente como para reconocer el número de ticket y asociarlo con el ticket que se está resolviendo. Eso significa que no se requiere una URL completa . También significa que puede obtener los beneficios y proporcionar comentarios significativos para el compromiso particular, todo en una línea.

Al ver el ticket en JIRA, verá la lista de cambios con todos los comentarios en contexto con la descripción, etc.

Berin Loritsch
fuente
Con respecto al comentario de las iniciales / fecha / descripción del cambio, aunque estoy de acuerdo en que buscar en el repositorio es mejor, quiero señalar que en mi último proyecto concluyeron que nuestros encabezados de archivo estándar con el año de copyright inicial combinado con un ejecutar el historial del software en el encabezado del archivo era evidencia suficiente para mantener actualizados los derechos de autor, por lo que si un archivo fuente comenzó en 2013 y se está actualizando hasta hoy (2018), entonces el hábito de actualizar el encabezado del archivo permitió que el copyright continúe sin trabajo adicional , minimizando la posibilidad de un lapso.
jia103
@ jia103, los encabezados de Copyright son un asunto diferente a comentar que una línea se cambió en tal o cual fecha usando las iniciales de alguien que puede o no ser parte del equipo en este momento. Una es una cuestión legal, la otra es información redundante simple que no proporciona contexto para comprender el código que está al lado.
Berin Loritsch
2

Sí, pero solo en casos raros.

En general, me imagino que la mayor parte del código se escribirá en relación con un boleto JIRA, por lo que no lo comentaría habitualmente con la identificación del boleto; de eso es de lo que se culpa. Pero en algunos casos, el código puede ser contradictorio, quizás la forma más obvia de escribir el código no funciona y hubo una discusión sobre por qué no en el boleto. En ese caso, consideraría agregar un comentario con la referencia del ticket.

Si una parte del código necesita solucionar un error conocido en otra parte, entonces también consideraría agregar una referencia de ticket.

No creo que esto lo vincule demasiado a JIRA, ya que si desea migrar de JIRA a un sistema alternativo, puede exportar sus problemas de JIRA como CSV e importarlos al otro sistema. La ID del problema puede cambiar durante ese proceso, pero debería poder conservar la ID del ticket JIRA en algún lugar de los tickets importados.

bdsl
fuente
1

Coloque los problemas de Jira en los comentarios de confirmación, luego use un complemento para vincular las confirmaciones con la Jira real.
Nuestros mensajes de compromiso comienzan con:

JIRA: XBVS-1222 Fixes bugs...

Por ejemplo, luego los ganchos entre bitbucket y jira vinculan los commits a la jira. Entonces es fácil ver con qué Jira se relaciona en eclipse, por ejemplo, haciendo clic derecho en el número de fila y seleccionando "Mostrar historial de revisiones" Creo que se llama así de todos modos. Su número de problema y los comentarios de Jira se resaltarán en la columna del número de fila, y al pasar el mouse por encima se le darán los detalles.

bot_bot
fuente
1
Un solo problema de Jira equivale a una sola rama y cada confirmación se anota con el identificador de Jira para un problema específico, tal como lo recomienda. Lo he usado durante mucho tiempo y usando git blame es una excelente manera de rastrear los cambios en el código y sus razones sin contaminar el código real con comentarios inútiles.
Andy
1

Ciertamente, no es una práctica terrible incluir problemas de JIRA en los comentarios de código, pero esta técnica combina de forma estrecha / manual dos preocupaciones dispares (problemas y código), y puede requerir actualizaciones de múltiples sistemas / ubicaciones (JIRA, en cualquier lugar de origen donde se menciona el problema) historial de control de versiones).

Los comentarios de código son problemáticos en general porque a menudo no se actualizan.

Un mejor enfoque sería encontrar alguna forma de integrar su sistema de seguimiento de problemas con su sistema de control de versiones, de modo que las dos preocupaciones se puedan mantener por separado, de manera automatizada.

mcknz
fuente