Buenos comentarios sobre los conjuntos de cambios en SourceControl [cerrada]

Question

Es necesario desarrollar directrices para escribir comentarios cuando se registra el código en el sistema de control de versiones (como TFS).

por ejemplo., Cuando nos sometemos una corrección de errores, creamos un comentario "Fixed bug # ..."

Tratamos a una lluvia de ideas sobre este tema, pero la mayoría de las ideas traen muy poco valor añadido.

Le agradecería cualquier sugerencia para esto.

Answer 1

En general, los comentarios que hacemos en los que trabajo son una descripción rápida de los cambios que se hicieron. Algo corto y simple.

Puede que no parece añadir mucho valor al principio, pero puede ser muy útil cuando se va hacia atrás a través de la historia tratando de encontrar cuando algo cambió (mucho más que un simple "error #####"). Ha habido un par de veces cuando tenía que volver atrás en la historia control de fuente para tratar de encontrar cuando un comportamiento o una pieza de código particular cambian, y las vistas generales rápidas pueden hacer que sea mucho más fácil de localizar dónde podría ser. Si acaba de dar un número de error, entonces usted tiene que hacer más trabajo para encontrar que la información básica (tire hacia arriba de seguimiento de errores y encontrar el error).

Answer 2

Mi (más concisa) orientación en torno a este tema está "para documentar ¿Por qué que están haciendo el cambio no lo ."

es decir. usted no debe decir "Solución de error en MyClass.cs y FooBar.cs", ya que el comentario es bastante irrelevante - que sólo puede mirar en el conjunto de cambios para encontrar esos detalles. Igualmente con TFS la vinculación de conjuntos de cambios a elementos de trabajo significa que la inclusión de la referencia de elemento de trabajo en el comentario es bastante superfluo. En lugar de una frase corta que explica la razón del cambio como "potencial vulnerabilidad XSS fija en el editor" es lo más útil para leer cuando se mira a través de una gran historia de conjuntos de cambios.

Answer 3

Para un cambio que se menciona en las notas de lanzamiento, incluyen una entrada de Notas de la versión sugerido , ya sea en el comentario de cambios o en el informe de error relacionado, si es que existe.

Al escribir una entrada de Notas de la versión, se ve obligado a dar un paso atrás y mirar a la edición desde el punto de vista del usuario. Esto le anima a describir sucintamente lo que era el problema y cómo la solución aborda el problema.

Answer 4

Puede configurar TFS a exigir que cualquier código de registro de entrada tiene una tarea TFS asociado a él.

El equipo de proyecto que lo utilice en la que trabajo requiere que todos los errores y / o características pueden introducir en TFS como tareas -. Y que cualquier código de registro de entrada se asocian con las tareas (s) que se aplica a

También se requiere un comentario, pero no tienen ningún directrices estrictas para lo que escribe, excepto para observar si no se requiere el cambio que se fusionen adelante a otra rama.

Answer 5

Si el cambio tiene un billete asociado a algún lugar o un insecto, en ese caso el número y el título (con un enlace) debería ser suficiente.

De lo contrario sólo especifique que el cambio hizo a implementar. directrices que comentan regulares se aplican, se puede comprobar algunos populares registro de proyecto para ver buenos ejemplos.

Answer 6

Cuando sea posible (como cuando se utiliza TFS para de seguimiento de errores y control de la fuente) vincular el registro directamente a un-elemento de trabajo apropiado. En su defecto, añadir el elemento de trabajo / Nº DE ERROR en los comentarios de cambios. Este es el nivel aceptable mínimo de observaciones de cambios.

El comentario registro debe describir el propósito de la modificación realizada, únicamente añadiendo detalles sobre la forma en que el cambio logra los resultados deseados, según sea necesario. Un buen punto de partida sería el título del elemento de trabajo correspondiente.

Uno o dos frases es una buena longitud de destino para el comentario. No sea tan general, el comentario no tiene sentido (por ejemplo, "ha corregido un error en xyz"), pero no ocultan la intención del cambio bajo capas de detalles innecesarios tampoco.

Answer 7

me gusta incluir una referencia al fallo (billete, la emisión, lo que cada vez su llama) si es posible, ya que proporciona el contexto y la motivación para el cambio. Además, me gusta tratar de responder a las preguntas ¿Qué ha cambiado y por qué en lo más cercano a una línea que pueda. Al hacer el comentario, trato de pensar en mi futuro auto en 6 meses mirando hacia atrás en los registros, diff, y la entrada de entender qué diablos estaba pensando. Entrar en demasiados detalles no parece ayudar.

Answer 8

1 para pegar el título cuestión de errores, que debe ser de carácter informativo.

1 para documentar por qué, si es necesario, además de título de errores.

1 por ser consciente de notas de la versión para cuando se desea informar a los clientes.

1 para la integración de SMC, seguimiento de errores, y CI, y haciéndolos enlazan entre sí sobre asuntos / insectos.