¿Es una buena idea una revisión de código que usa solo comentarios de código?

Condiciones previas

• El equipo usa DVCS
• IDE admite el análisis de comentarios (como TODO y etc.)
• Herramientas como CodeCollaborator son caras para el presupuesto
• Las herramientas como gerrit son demasiado complejas para instalar o no se pueden usar

Flujo de trabajo

• El autor publica en algún lugar de la rama de funciones de repositorio central
• El revisor lo busca y comienza a revisar

• En caso de que algún revisor de preguntas / problemas cree un comentario con una etiqueta especial, como "REV". Dicha etiqueta NO DEBE estar en el código de producción, solo en la etapa de revisión:

  $somevar = 123;
  // REV Why do echo this here?
  echo $somevar;
  

• Cuando el revisor termina de publicar comentarios, solo se compromete con mensajes estúpidos "comentarios" y retrocede

• El autor retira la rama de la función y responde comentarios de manera similar o mejora el código y lo retrocede
• Cuando los comentarios "REV" han desaparecido, podemos pensar que esa revisión ha finalizado con éxito.
• El autor reajusta interactivamente la rama de la característica, la aplasta para eliminar esas confirmaciones de "comentario" y ahora está listo para fusionar la característica para desarrollar o realizar cualquier acción que normalmente podría ocurrir después de una revisión interna exitosa

Soporte IDE

Sé que las etiquetas de comentarios personalizados son posibles en eclipse y netbeans. Claro que también debería estar en la familia blablaStorm.

Preguntas

1. ¿Crees que esta metodología es viable?
2. ¿Sabes algo similar?
3. ¿Qué se puede mejorar en él?

La idea es realmente muy buena. Al contrario de los flujos de trabajo comunes, mantiene la revisión directamente en el código, por lo que técnicamente, no necesita nada más que editor de texto para usar este flujo de trabajo. El soporte en el IDE también es bueno, especialmente la capacidad de mostrar la lista de revisiones en la parte inferior.

Todavía hay algunos inconvenientes:

• Funciona bien para equipos muy pequeños, pero los equipos más grandes requerirán un seguimiento de lo que se revisó, cuándo, por quién y con qué resultado. Si bien realmente tiene este tipo de seguimiento (el control de versiones permite saber todo eso), es extremadamente difícil de usar y buscar, y a menudo requerirá una búsqueda manual o semi-manual a través de las revisiones.

• No creo que el revisor tenga suficientes comentarios del revisor para saber cómo se aplicaron realmente los puntos revisados .

  Imagina la siguiente situación. Alice está revisando por primera vez el código de Eric. Se da cuenta de que Eric, un desarrollador joven, usó la sintaxis que no es la más descriptiva en el lenguaje de programación realmente utilizado.

  Alice sugiere una sintaxis alternativa y envía el código a Eric. Reescribe el código utilizando esta sintaxis alternativa que cree que comprende correctamente, y elimina el // BLAcomentario correspondiente .

  La próxima semana, ella recibe el código para la segunda revisión. ¿Sería capaz de recordar realmente que hizo este comentario durante su primera revisión, para ver cómo Eric lo resolvió?

  En un proceso de revisión más formal, Alice pudo ver de inmediato que hizo un comentario y ver la diferencia del código relevante, para notar que Eric no entendió la sintaxis que le contó.

• La gente sigue siendo gente. Estoy bastante seguro de que algunos de esos comentarios terminarán en el código de producción, y algunos permanecerán como basura mientras estén completamente desactualizados .

  Por supuesto, el mismo problema existe con cualquier otro comentario; por ejemplo, hay muchos comentarios TODO en producción (incluido el más útil: "TODO: Comente el código a continuación"), y muchos comentarios que no se actualizaron cuando se realizó el código correspondiente.

  Por ejemplo, el autor original del código o el revisor pueden irse, y el nuevo desarrollador no entendería lo que dice la revisión, por lo que el comentario permanecerá para siempre, esperando que alguien sea demasiado valiente para borrarlo o para entender realmente qué dice.

• Esto no reemplaza una revisión cara a cara (pero el mismo problema se aplica también a cualquier otra revisión más formal que no se haga cara a cara).

  Especialmente, si la revisión original requiere una explicación, el revisor y el revisor comenzarán una especie de discusión . No solo se encontrará con grandes comentarios de BLA, sino que esas discusiones también contaminarán el registro del control de versiones .

• También puede encontrar problemas menores con la sintaxis (que también existe para los comentarios TODO). Por ejemplo, ¿qué pasa si un comentario largo "// BLA" se genera en varias líneas y alguien decide escribirlo de esta manera:

  // BLA This is a very long comment which is way beyond 80 characters, so it actually
  // fills more then one line. Since the next lines start with slashes, but not "BLA"
  // keyword, the IDE may not be able to show those lines, and display only the first one.
  

• Y, por último, como una nota menor y muy personal: no elija "BLA" como palabra clave. Suena feo ;)

Complementaría los comentarios en el código con un documento complementario. Esto resumiría los hallazgos y seguiría vivo después de que se eliminaran los comentarios. Las ventajas de esto serían:

• compacidad Si la persona rutinariamente falla en verificar que un puntero que se pasa no sea nulo (o algún otro error de principiante común en el idioma que está usando), el revisor puede dejar docenas de comentarios REV en ese sentido, y en el documento puede decir " Encontré 37 lugares donde los punteros no se verificaron primero "sin enumerarlos todos
• Lugar de alabanza. Un comentario comoREV this is a nice design simplemente parece un poco extraño, pero mis revisiones de código a menudo incluyen aprobación y correcciones
• interactividad Su comentario de muestra es "¿por qué hiciste esto?" y es muy típico Un enfoque de solo comentarios no admite una conversación. La persona puede cambiar su código y eliminar el comentario, o eliminar el comentario. Pero "¿por qué hiciste esto?" y "por favor cambia esto, está mal" no son lo mismo.
• llevar un registro Un revisor posterior puede verificar si el código se cambió realmente o si se eliminaron los comentarios. También pueden verificar que los comentarios se hayan "tomado en cuenta" y que el desarrollador ya no cometa los mismos errores en una revisión posterior.

También usaría un elemento de trabajo para hacer la revisión y responder a la revisión, y asociar los registros con ella. Eso facilita encontrar los comentarios en un conjunto de cambios antiguo y ver cómo se manejó cada uno en otro conjunto de cambios.

Otros han hablado de las limitaciones de este enfoque. Usted mencionó que las herramientas como Gerrit eran difíciles de instalar. Le sugiero que eche un vistazo a phabricator (http://www.phabricator.com). Este es el sistema de revisión de código que Facebook ha usado durante años, y recientemente fue de código abierto. No es difícil de instalar, tiene excelentes flujos de trabajo y resuelve todos los problemas mencionados en los otros comentarios.