¿Cómo puedo convencer a mis compañeros de desarrollo de que QUIEREN agregar comentarios a las confirmaciones de código fuente?

Centrarse en "por qué". Todo está muy bien mirando las diferencias y viendo que alguien cambió el flujo lógico de una sección de código o algo así, pero ¿por qué lo cambiaron? El por qué suele estar en el ticket asociado (JIRA para usted).

Es posible que se pregunten por qué el "Por qué" es importante, pero dentro de 2 años, cuando haya detectado un error que es un golpe en el efecto de ese cambio, saber por qué se hizo es increíblemente importante no solo para corregir su nuevo error. pero asegurándote de que no vuelvas a surgir el error anterior.

También existe la razón de la auditoría. Las confirmaciones de enlace y los identificadores de tickets hacen que sea realmente fácil decirlo, estamos eliminando la versión 2, esto corrige los defectos 23, 25, 26 y 27, pero no hay confirmaciones contra el defecto 24, por lo que aún está pendiente.

Haz que hagan las fusiones y lidien con el soporte. Una vez más, tal vez no esté en condiciones de hacer esto, pero si se encuentra siendo el único en solucionar un problema de un compromiso anterior, envíelo educadamente a la valla y dígalo. No puedo decir lo que hizo porque no hay comentarios de confirmación, hizo estos cambios que necesita para resolverlo.

También para fusionar ramas. No estoy seguro de si eso te incumbe o no, pero es un área en la que los comentarios me parecieron útiles.

Nuevamente, no en su barco, pero cuando gestioné un equipo de software les dije que si hacían buenos comentarios de confirmación los usaría para obtener un informe de estado semanal. Obtuve excelentes confirmaciones después de eso y me fue más fácil hacer un seguimiento de lo que estaba sucediendo como gerente también.

Necesitamos comentarios de entrada por la misma razón por la que necesitamos saltos de línea y espacios en nuestro código. Para facilitar el seguimiento de las cosas, comprenda leer y comprender.

A veces es necesario comparar, pero a menudo no es así. Forzar a los desarrolladores a hacer comparaciones cuando todo lo que necesitaban era leer 2-3 oraciones es una pérdida total de tiempo. Me pregunto por qué no ven el valor del tiempo de desarrollador.

• Dé un buen ejemplo. Haz de tus propios mensajes de confirmación un brillante ejemplo de utilidad. Incluya referencias a cualquier otro sistema que su equipo use para administrar historias y defectos. Ponga una breve declaración que resuma el cambio y una buena explicación de por qué el cambio es necesario y no algo más en cada presentación.
• Siempre que la falta de un mensaje de confirmación decente le cause un trabajo extra, envíe una pregunta al remitente. Sea persistente con esto (pero no un imbécil).
• Si no está sobrepasando tu rol, escribe un script que envíe un registro de cambios diario usando los mensajes de confirmación. Esto le dará credibilidad a su argumento de que los mensajes útiles tienen un beneficio más allá de la navegación a través de las revisiones. Esto también podría ayudar a que la administración esté de su lado, ya que verán el día a día lo que sucede.
• Identifica a tus aliados. Esperemos que haya al menos otra persona que esté de acuerdo con usted (tal vez en silencio no en desacuerdo). Encuentra a esa persona o a esas personas y convencelas para que no estés solo.
• Cuando se presente la oportunidad de mencionar cómo los mensajes de confirmación decentes le han ahorrado tiempo (o los mensajes de baja calidad le han costado tiempo), aproveche.

No tengas miedo de ser la rueda chirriante. Luchar contra los malos hábitos de otras personas es a menudo una guerra de desgaste.

Esta tiene que ser una de las preguntas más extrañas que he escuchado. ¿Las personas pasan horas o incluso días arreglando algo y 2 segundos adicionales para escribir un mensaje de confirmación es demasiado largo? Debo decir que me preocuparía trabajar con personas tan miopes. Obviamente, no están utilizando sus herramientas ni siquiera para alcanzar todo su potencial.

Aquí hay un ejemplo de una revisión de código en la que participé la semana pasada. Nuestro software de control de versiones no conserva el historial a través de las combinaciones, por lo que para los cambios más antiguos debe encontrar la rama exacta en la que se realizó, de lo contrario, el mensaje de confirmación solo muestra algo como "fusionado desde la rama Y" La rama Y puede mostrar "fusionada desde la rama Z", y una rama a unos pocos niveles de anidamiento más profundo en realidad tiene el mensaje de confirmación real.

Un nuevo empleado no sabía cómo rastrear el historial correctamente, lo que significa que esencialmente estaba trabajando solo con las diferencias. Vio algunos códigos comentados relacionados con el error que estaba rastreando. Cuando él no comenta el código, su error desapareció. Supuso que alguien había comentado el código durante la depuración y lo había registrado por error.

Eso no nos pareció correcto para un par de nosotros durante la revisión del código, así que localicé el mensaje de confirmación real y descubrí que había una razón válida para eliminar ese código hace un año. El nuevo empleado pudo corregir su código para corregir el error recién descubierto sin reintroducir el anterior.

Hay mejores maneras de evitar la introducción de este tipo de regresiones, como pruebas de unidad completas, pero de alguna manera no veo a personas que no puedan molestarse con un mensaje de confirmación de 2 segundos que "desperdicia" el tiempo en la prueba de unidad.

Tenía exactamente el mismo problema aquí, así que agregué un enlace pre-commit para Subversion, por lo que no aceptaría ninguna confirmación que no comenzara con el número de User Story (algunos patrones básicos coincidentes para un formato esperado).

No hay nada que les impida ingresar 000-0000, pero una vez solo un idiota disruptivo formará un número cuando tenga un número perfectamente aceptable allí.

Hice esto después de pasar días tratando de encontrar en qué se construye un conjunto de historias de usuarios. Sí, fue para hacer frente a un fallo del proceso en otro lugar, pero sigue siendo increíblemente información valiosa para rastrear.

Los buenos comentarios de confirmación son como cualquier buena documentación, un caché para tu cerebro lento y difunto o un caché del resultado de cualquier larga depuración / análisis de problemas / investigación.

Por ejemplo, Cada vez que dedica tiempo a averiguar algo, como la depuración, el análisis de registros o lo que sea, sus hallazgos y resultados son preciosos. Por supuesto, la mayoría de las tareas se pueden repetir, pero puede llevar tiempo. Así que siempre debes documentar tus resultados.

Aún así, la documentación lleva tiempo y, a veces, se siente como no necesaria, como "solo tuvimos que hacer esto una vez, así que por qué escribirla". Eso está bien, pero tan pronto como haces lo mismo por segunda vez porque no documentaste los resultados la primera vez, por supuesto es inteligente documentar los resultados.

Entonces, si sus colegas consideran que es demasiado trabajo agregar comentarios de compromiso, por ejemplo, al menos señalar el caso / Ticket de Jira que estaban resolviendo, entonces, podrían estar motivados por la presión de responder constantemente a las preguntas relacionadas con el motivo de cada conjunto de cambios.

En mi opinión, la documentación se debe producir en función de la información que se solicita. Por ejemplo, la correspondencia por correo es un buen sistema de documentación. Las preguntas reciben respuestas que se pueden recuperar posteriormente, así es como las listas de correo y los foros funcionan en la práctica como bases de conocimiento.

Lamentablemente, donde trabajo, el correo se elimina automáticamente después de 3 meses, por lo que no siempre funciona en la práctica.

Busca el perdón, no el permiso.

Mientras duro, hice justo esto. Tuve una división del 50/50 entre las personas que apoyan y las personas que se oponen, la mayoría de los cuales tenían el mismo nivel que yo en el grupo. Los argumentos fueron "No puedo ser molestado" y "¿Cuál es el punto?". (Ambos indican apatía y pereza, no preocupaciones genuinas).

Agregué un enlace de precompromiso que simplemente medía la longitud de la cuerda y daba un mensaje ligeramente cómico antes de rechazarlo. Puse mi nombre en el mensaje para que la responsabilidad por "esta indignación" fuera clara. Por supuesto, "la oposición" podría eliminarlo fácilmente, ¡pero profundizar en los scripts requeriría más esfuerzo que agregar un comentario más!

Durante una semana recibí mensajes agregados como * * (se eliminó un poco) o kjhfkwhkfjhw. Después de eso, empezaron a aparecer mensajes básicos.

Un año después, los escépticos usan comentarios significativos y realmente admiten que eran de poca visión. Nunca pude haber llegado a un consenso, pero ciertamente obtuve perdón y quizás credibilidad. Funciona, la gente lo usa.

Si deseaba ser más amable (o cree que tendría problemas), pida permiso para agregar un enlace de confirmación para un período de prueba. Diga que si a la gente no le gusta en 2 semanas o 4 semanas, lo eliminará. Es probable que pierdan interés ... o que les guste.

Generalmente convenzo a la gente a través de:

• dialéctica con buenas razones de apoyo
• liderando con el ejemplo
• desgaste

Si quisiera que nuestro equipo hiciera algo suficientemente malo, seguiría molestándome hasta que me salga con la mía. Intento molestar en esos momentos en los que puedo señalar que podríamos haber ahorrado tiempo / dinero si ya hubiéramos estado haciendo X.

Buenas razones adicionales para cometer comentarios:

• Generando ChangeLog automáticamente a partir de los comentarios.
• Registro de auditoría para correcciones de errores, adiciones de funciones. Esto es útil tanto dentro como fuera del equipo.
• Haz que el correo de confirmación sea más útil.
• Evita que le pregunte al desarrollador qué hace X (después de casi cada confirmación).

• Revise sus registros de SVN para ver si hay algo oscuro hecho hace 6 meses.
• Haz algunas preguntas sobre esto sin decir cuándo se ha hecho
• ???
• Beneficio

¿Cómo haces que quieran agregar buenos comentarios?

De una experiencia con un colega que acabo de tener. Al final de un proyecto, tuvimos que escribir un documento de resumen de todos los cambios realizados a lo largo del proyecto. Al no haber hecho buenas notas de confirmación, mi colega encontró que esta tarea consumía bastante tiempo y ahora ha pasado a hacer comentarios bastante largos con cada confirmación.

Por lo tanto, para llevar, una solución podría ser que los desarrolladores escriban documentos de resumen al final del proyecto que detallan qué cambios se realizaron en qué archivos, qué archivos se agregaron / eliminaron y por qué.

Propóngalo a la administración a puerta cerrada:

El peor escenario ocurre: todos los desarrolladores de nivel superior salen por la puerta.

A medida que la empresa se apresura a ocupar puestos vacantes de desarrolladores, el equipo de administración tiene la tarea de comunicar el estado del sistema al cliente.

Pregúnteles qué creen que les facilitaría su trabajo para reconstruir el historial de la aplicación:

¿Leer las confirmaciones en inglés simple que describen claramente el estado cambiante del sistema?

¿O preferirían ver las diferencias de código y resolverlas por sí mismas?

Supongo que una forma de convencerlos sería experimentar el dolor que sientes.

Por ejemplo, digamos que están trabajando en el siguiente problema: tienen un error que, de alguna manera, apareció cuando se implementó otra solución de error para el mismo código (oh, la ironía). Ser capaz de buscar esto desde solo buscar a través de los mensajes de confirmación sería genial (y, por lo tanto, descubrir quién lo escribió).

Otra forma sería explicarles que el mensaje de confirmación podría ser útil para dar una idea de por qué algo se implementó de cierta manera. Incluso si el mensaje de confirmación solo dice "característica X", aún puede obtener una pista de quién lo implementó, para que sepa con quién hablar.

  

Sin embargo, esto no parece ser suficiente para combatir las dos respuestas.   siempre obtenga:

     

1. Lleva demasiado tiempo y solo quiero introducir mis cambios en el repositorio.
  
2. Es bastante fácil simplemente mirar las diferencias.
  

¿Ha intentado lanzar un desafío a sus compañeros desarrolladores para que obtengan algún otro beneficio al hacer comentarios? Uno podría ver esto desde cualquiera de los dos ángulos diferentes:

1. Mejorando su juego: esta puede ser la perspectiva más difícil de tomar, pero la idea aquí sería que lo hagan durante un período de tiempo y se acostumbren a la idea, de modo que el hábito es que tomaría más tiempo ir al otro lado . Otro punto aquí es ¿cuánto escrutinio obtendrían los comentarios? Si quieres una historia corta en el comentario, podría entender su punto.
2. Subsidiar un cambio: aquí es donde tendrías algún tipo de concurso como una forma de tener la compra inicial para probar esto u ofrecer algún otro tipo de incentivo para que el cambio se haga por un tiempo.

Algo más a considerar es qué tan bien sabe lo que sus colegas desarrolladores están administrando en su trabajo. Si están tratando de hacer 10 cosas ayer, entonces podría entender que no quieren cambiar lo que ven como algo que ya funciona. ¿Estás tratando de decirles, "No, esto no funciona?" Si es así, entonces puedo ver cómo pueden ser un poco defensivos o combativos en esto. Si está tratando de decirles: "Si bien esto puede funcionar, hay una alternativa que puede ser mejor ..." entonces es posible que tenga una oportunidad. Tener una actitud de "más sagrado que tú" aquí no te ayudará, IMO.

Otra forma de ver esto es como una forma en que los desarrolladores involucrados pueden hacer crecer sus carreras: deberían own the documentation de su trabajo.

Además de otros puntos planteados en el artículo mencionado anteriormente, existe la posibilidad de poder revisar los cambios de código para averiguar dónde / cuándo / por qué se realizó un cambio. Eso podría ser vital cuando se rastrea un error difícil de alcanzar.

Una vez que los haya convencido de que es importante comentar sus confirmaciones, puede crear un script que obligue a los comentarios a realizar confirmaciones, de lo contrario fallará. Incluso puede especificar un mínimo de caracteres para garantizar que sea un comentario significativo. Esto les ayudará a "recordar".

Sin embargo, es importante que comprendan el Porqué como dijo @Kevin, o de lo contrario simplemente agregarán cualquier comentario aleatorio.

¿Tienes revisiones de código? Una cosa que puede ayudar es instituir una regla de que cualquier compromiso o fusión debe ser revisado y aprobado por otro desarrollador. Entonces, si usted es el revisor, tendrá que pedirle al desarrollador que se comprometa a explicarle lo que hizo. Una vez que lo haga, debes pedirle que escriba en el comentario lo que te acaba de decir. A menudo, cuando uno no puede explicar de manera coherente los cambios realizados, significa que dichos cambios no deberían haberse realizado en primer lugar.

Tengo que decir, sin embargo, ¿cómo pueden las personas objetar algo tan obviamente útil como comentar comentarios? No toma mucho tiempo, y es un tiempo bien empleado. Escribir un comentario te obliga a pensar qué es lo que acabas de hacer. Incluso puede hacer que mire las diferencias para asegurarse de que realmente ha hecho lo que cree que ha hecho y que no ha hecho nada estúpido.

Cuando no escribes los comentarios, estás siendo descuidado e indisciplinado. Y si insiste en que no se le debe exigir que escriba los comentarios, entonces está siendo voluntariamente negligente.

Dígales que es la única forma de tener la oportunidad de mantener su desorden de procedimientos de 50,000 métodos de línea, luego considere escribir un código mejor y más explícito en el futuro para que no tenga que lidiar con un montón de comentarios sin sentido que hacen que su base de código.

Este es un elemento de cambio de proceso: haga que un administrador asigne un código desarrollado por "x" a "Y" para verificaciones de control de calidad solo en el código, incluido el control de calidad de los comentarios.

En mi propia organización, a los desarrolladores no se les permite realizar el control de calidad final de su propio código y verificarlo, esto lo debe hacer otro desarrollador. Parte del QA Check son los comentarios, por lo que no hay comentarios ni controles. Hacemos muchos trabajos por contrato en los que nuestro "arte" es en realidad la propiedad intelectual contractual de otra persona, por lo que otros necesitan poder entender y aprovechar nuestro código. Además, hay ocasiones en que los proyectos vuelven a nosotros después de una larga pausa y necesitamos poder recoger el código 18-24 meses más tarde y comprender el por qué, dónde y cómo llegamos al artefacto del código que tenemos delante. Esto proporciona una motivación egoísta para escribir comentarios de confirmación.

Pregunte y haga que sus compañeros desarrolladores realicen algunas combinaciones, busquen el historial y comparen algunos archivos del historial.

Lo más probable es que te pidan que pongas comentarios al día siguiente.

Aquí hay algunos consejos:

1. No trates de cambiar el mundo. Vas a fallar.
2. En su lugar, debe reconocer que todos trabajan de forma ligeramente diferente. No hay una talla única para todos.
3. requerir algunos pasos específicos para los procesos de trabajo de las personas es muy malo. Cambiar estos procesos lleva 10 años. Les está pidiendo que hagan esto antes de la próxima fecha límite.
4. Incluso los cambios de proceso simples pueden llevar mucho tiempo.
5. Algún pequeño comentario sobre las confirmaciones es demasiado insignificante para cambiar estos procesos.
6. Puede asumir que hacen un trabajo de calidad, pero deben dar suficiente libertad para elegir los pasos por sí mismos. Es posible que no se necesiten algunos pasos complicados para desarrolladores con experiencia.
7. Si estás cuidando a los novatos, entonces podrían ser necesarios procesos más sólidos, pero los desarrolladores con experiencia no deberían lidiar con la mierda.
8. Imponer restricciones draconianas sobre cómo se debe hacer el trabajo nunca va a funcionar, solo puede ralentizar a las personas (podría ser bueno si son demasiado rápidos)
9. Hay muchas personas que piensan que su camino es la única manera correcta de hacer las cosas. Espero que no seas uno de ellos.

Si su control de código fuente lo permite, active los comentarios obligatorios para evitar cualquier comisión sin comentarios. Bastante simple y todos pronto se darán cuenta de que 5 segundos al escribir un comentario es indoloro.

Pero los compromisos sin comentar son uno de los negativos más pequeños que hay. He sido parte de muchos proyectos exitosos donde no se comentó un solo compromiso. No pongas tus bragas en un montón por encima.