Frustraciones de revisión por pares / código

No me llamaría un desarrollador superestrella, sino relativamente experimentado. Intento mantener la calidad del código a un alto nivel, y siempre busco mejorar mi estilo de codificación, intentar que el código sea eficiente, legible y coherente, así como alentar al equipo a seguir patrones y metodologías para garantizar la coherencia. También entiendo la necesidad del equilibrio entre calidad y velocidad.

Para lograr esto, he presentado a mi equipo el concepto de revisión por pares. Dos pulgares arriba en github pull-request para una fusión. Genial, pero no en mi opinión sin hipo.

A menudo veo comentarios de revisión por pares de los mismos colegas como:

• Sería bueno agregar un espacio después <INSERT SOMETHING HERE>
• Línea extra no deseada entre métodos
• El punto final debe usarse al final de los comentarios en docblocks.

Ahora desde mi perspectiva, el revisor está mirando superficialmente la estética del código, y realmente no está realizando una revisión del código. La revisión del código cosmético me parece una mentalidad arrogante / elitista. Carece de sustancia, pero no se puede discutir demasiado porque el revisor es técnicamente correcto . Preferiría ver menos de los tipos de revisiones anteriores y más revisiones de la siguiente manera:

• Puede reducir la complejidad ciclomática ...
• Salga temprano y evite si / si no
• Resuma su consulta de base de datos a un repositorio
• Esta lógica realmente no pertenece aquí
• No te repitas: abstrae y reutiliza
• ¿Qué pasaría si Xse pasara como argumento al método Y?
• ¿Dónde está la prueba de unidad para esto?

Creo que siempre son los mismos tipos de personas quienes dan los tipos cosméticos de revisiones, y los mismos tipos de personas que, en mi opinión, dan las revisiones por pares "basadas en la calidad y la lógica".

¿Cuál (si lo hay) es el enfoque correcto para la revisión por pares? ¿Y estoy en lo correcto al sentirme frustrado con las mismas personas que básicamente pasan por alto el código en busca de errores ortográficos y defectos estéticos en lugar de defectos de código reales?

Si estoy en lo correcto, ¿cómo podría alentar a mis colegas a buscar fallas en el código en equilibrio con sugerir retoques cosméticos?

Si soy incorrecto, por favor, ilumíneme. ¿Existen reglas generales para lo que en realidad constituye una buena revisión de código? ¿Me he perdido el punto de qué son las revisiones de código?

Desde mi perspectiva, la revisión del código se trata de la responsabilidad compartida del código. No me sentiría cómodo dando el visto bueno al código sin direccionar / verificar la lógica, la legibilidad y la funcionalidad. Tampoco me molestaría en bloquear una fusión para un código sólido si me di cuenta de que alguien ha omitido una parada completa en un bloque de documentos.

Cuando reviso el código, gasto entre 15-45 minutos por 500 Loc. No puedo imaginar que estas revisiones superficiales tarden más de 10 minutos si esa es la profundidad de la revisión que están realizando. Además, ¿cuánto valor tiene el pulgar hacia arriba del crítico superficial? Seguramente esto significa que todos los pulgares no tienen el mismo peso y es necesario que haya un proceso de revisión de 2 pases. ¿Un pulgar para revisiones profundas y un segundo pulgar para el "pulido"?

Tipos de reseñas

No hay una única forma real de hacer evaluaciones por pares. Hay muchas maneras de juzgar si el código es de una calidad suficientemente alta. Claramente está la cuestión de si tiene errores o si tiene soluciones que no escalan o que son frágiles. Los problemas de conformidad con las normas y directrices locales, aunque quizás no sean tan críticos como algunos de los otros, también son parte de lo que contribuye al código de alta calidad.

Tipos de revisores

Así como tenemos diferentes criterios para juzgar el software, las personas que juzgan también son diferentes. Todos tenemos nuestras propias habilidades y predilecciones. Algunos pueden pensar que cumplir con los estándares locales es muy importante, al igual que otros podrían estar más preocupados por el uso de la memoria o la cobertura del código de sus pruebas, etc. Desea todos estos tipos de revisiones, porque en su conjunto lo ayudarán a escribir un mejor código.

Una revisión por pares es colaboración, no un juego de etiqueta

No estoy seguro de que tengas derecho a decirles cómo hacer su trabajo. A menos que sepa lo contrario con certeza, suponga que esta persona está tratando de contribuir de la manera que le parezca más conveniente. Sin embargo, si ve margen de mejora o sospecha que tal vez no entienden lo que se espera en una revisión por pares, hable con ellos .

El objetivo de una revisión por pares es involucrar a sus pares . La participación no es arrojar código sobre una pared y esperar que se devuelva una respuesta. La participación está trabajando en conjunto para crear un mejor código. Participe en una conversación con ellos.

Consejo

Hacia el final de su pregunta, escribió:

¿Cómo podría alentar a mis colegas a buscar fallas en el código en equilibrio con errores estéticos evidentes?

De nuevo, la respuesta es la comunicación. Tal vez pueda preguntarles "oye, agradezco que descubran estos errores. Me ayudaría enormemente si también pudiera enfocarse en algunos problemas más profundos, como si estoy estructurando mi código correctamente. Sé que lleva tiempo, pero realmente ayuda."

En una nota más pragmática, personalmente divido los comentarios de revisión de código en dos campos y los expreso apropiadamente: cosas que deben arreglarse y cosas que son más cosméticas. Nunca evitaría que se registre un código de trabajo sólido si hubiera demasiadas líneas en blanco al final de un archivo. Sin embargo, lo señalaré, pero lo haré con algo como "nuestras pautas dicen que tiene una sola línea en blanco al final, y usted tiene 20. No es un obstáculo, pero si tiene la oportunidad, usted podría querer arreglarlo ".

Aquí hay algo más a tener en cuenta: puede ser una manía tuya que hagan una revisión tan superficial de tu código. Puede muy bien ser que un motivo favorito de los suyos es que usted (o algún otro compañero de equipo que consigue un examen similar) está descuidado con respecto a los estándares de codificación de su propia organización, y esta es la forma en que han elegido para comunicarse con ustedes.

¿Qué hacer después de la revisión?

Y, por último, un pequeño consejo después de la revisión: al confirmar el código después de una revisión, es posible que desee considerar cuidar todas las cosas cosméticas en una confirmación y los cambios funcionales en otra. Mezclar los dos puede dificultar la diferenciación de los cambios significativos de los insignificantes. Realice todos los cambios cosméticos y luego confirme con un mensaje como "cosmético; sin cambios funcionales".

La gente comenta sobre el formato de código y los errores tipográficos porque son fáciles de detectar y no requieren mucho esfuerzo de su parte.

Esta parte es fácil de solucionar: casi cualquier idioma tiene una herramienta de verificación de estilo o de linter. Conéctelo en su proceso de compilación, para que falle la compilación si hay un espacio redundante. Como resultado, no habrá problemas de estilo para comentar.

Hacer que encuentren problemas reales puede ser todo un desafío. No solo esto requiere una mentalidad especial inquisitiva y orientada a los detalles, sino también una motivación significativa.

Y esta motivación proviene de la experiencia. Experiencia de tratar de trabajar con código basura escrito por desarrolladores anteriores. Los ingenieros superiores tienen mucho de eso. Nadar en el océano de mierda te da un gran deseo de no volver allí.

Si necesito elegir una cosa principal para verificar durante la revisión del código, sería la mantenibilidad del código. En todo momento, el desarrollador que revisa este código debe comprenderlo y estar listo para mejorarlo y modificarlo. Si no tiene idea de lo que está sucediendo aquí, debe informarlo de inmediato y el código debe reescribirse.

Aquí viene la respuesta práctica:

Escenario 1 : usted es el miembro principal y alguien que puede decidir la práctica

Convoque una reunión y establezca las reglas y pautas de Revisión del Código. Confía en mí, las pautas claras funcionan mejor que cualquier sistema o entrenamiento de 'honor'. Deje en claro que los problemas de formato de código no deben plantearse en absoluto. Algunos miembros se opondrán. Escúchelos y luego pídales que sigan las pautas durante los primeros meses como experimento. Mostrar disposición a cambiar si las pautas actuales no funcionan.

Escenario 2 : no eres alguien que decide la práctica o eres un miembro relativamente menor en el equipo

Su mejor opción es resolver los problemas de revisión de código hasta que logre alcanzar el escenario 1 .

La respuesta simple para evitar comentarios de revisión de código "triviales" es insistir (en aras de la eficiencia) en que el revisor debe ser quien los repare. Entonces, si el revisor encuentra que (¡horror!) Se perdió un paro completo o deletreó un comentario incorrectamente, debería solucionarlo y seguir adelante.

En mi experiencia, esto significa que:

• sus revisores dejan de hacer estos comentarios de revisión relativamente inútiles y los devuelven para que sean reparados.
• solo la mayoría de los revisores de TOC los corregirán, lo que significa que la mayoría de sus revisiones pasarán. esto tiene el efecto de exigir que los desarrolladores realicen revisiones más sustantivas, aquellos que informan trivia porque en realidad no están revisando el código terminarán teniendo que justificar por qué todas sus revisiones pasan sin comentarios.

De cualquier manera, esto es un beneficio. El costo de una revisión fallida es alto en términos de hacer que un desarrollador detenga lo que está trabajando y revise su código, y la posterior revisión de seguimiento. Si una revisión encuentra calidad de código real o problemas arquitectónicos, entonces este costo vale cada centavo, pero pagar este costo por curiosidades no lo es.

Revisar el proceso de revisión

Además de las revisiones de código, sugeriría que también revise el proceso de revisión de forma regular. Ciertamente, también hay muchas cosas que las personas pueden aprender aquí, por ejemplo, cómo dar revisiones de código adecuadas.

Por lo general, algunos de los deslaminadores de bicicletas no tienen experiencia y simplemente no saben qué buscar. Necesitan un poco de orientación no solo con respecto a su código, sino también frente a hacer revisiones de código útiles. Brindar comentarios sobre las revisiones conducirá a un proceso de aprendizaje que (optimistamente) dará como resultado mejores revisiones y un mejor código.

Luego, podría ser una buena idea formalizar (libremente) un conjunto de valores y criterios, lo que la organización o el equipo percibe como Good Code ™ y cuáles son los antipatrones que deben evitarse. No se trata de establecer algo. en concreto, pero acerca de obtener un consenso común sobre la calidad del código desde el principio .

Como alguien que ha estado en ambos lados de esto (revisando el código escrito por otros, además de haber revisado el código que he escrito), diría que tengo tres categorías en las que cae cualquier comentario. Bueno, cuatro, también está el delicioso caso de "todo está bien".

"Sería bueno, pero no lo bloqueará" (si todos los comentarios entran en esta categoría, puedo enviar la solicitud de fusión con un "se fusionará a las XX: XX, a menos que me diga que desea solucionarlos" , o "seguro, adelante para registrarse, cualquier bloque que arroje el sistema ha sido desactivado"):

• Olvidando los puntos completos al final de las oraciones (en cadenas de documentos o comentarios). Gramática torpe en cualquier cosa que no se emita a los usuarios de ninguna manera o forma (de nuevo, cadenas de documentos y comentarios)
• Código que tiene una forma más elegante, pero lo que hay allí es comprensible e idiomático (probablemente incluso pondré mi sugerencia, por lo que es fácil dejarlo o arreglarlo)

"Cosas que deben arreglarse, pero confiaré en que hagas eso" (si todas las cosas caen en esta o en la categoría anterior, responderé con "arregla esto, me fusionaré cuando me digas" re done "(y en ese momento probablemente escanearé rápidamente para ver que no apareció nada más):

• Pequeñas objeciones ("estás comparando un booleano true, eso es un poco paranoico ...", ...)
• Violaciones de estilo menores ("la guía de estilo dice X, lo que has hecho está fuera de eso; yo haría Y o Z, dependiendo de la forma en que quieras ir")
• Algunos casos de prueba faltantes, que no deberían ser difíciles de escribir

Y finalmente, "las cosas que son problemáticas, tendré que revisar su código nuevamente una vez que haya solucionado estos problemas" (si hay alguna en esta categoría, deberá haber otra ronda de revisión, así que escriba un comentario que diga " también hay un par de cosas menores, sería bueno ver algunas de esas reparaciones mientras lo hace "si hay algo de las dos primeras categorías presentes):

• Esto sería cosas como "no, realmente hay una manera MUCHO mejor de escribir que", "no está calculando lo que espera, porque su prueba unitaria pierde estos casos extremos" y todos los demás problemas graves.

Parece que algunas personas han olvidado la pregunta más importante: ¿Qué es lo que realmente quieres lograr con las revisiones de código?

El propósito de las revisiones de código es obtener código libre de errores y fácil de mantener más rápido. Las revisiones de código logran esto de varias maneras: los desarrolladores escriben mejor código en primer lugar porque saben que será revisado, el conocimiento se comparte como parte del proceso de revisión, se encontrarán errores porque el revisor no es ciego a sus propios errores como desarrolladores puede ser.

Si ve el proceso de revisión como una oportunidad para despreciar a sus colegas, o para crear trabajo para ellos, entonces lo está haciendo mal.