¿Cuál es la mejor manera de comentar en una revisión de código?

Mi equipo acaba de comenzar a usar crisol / ojo de pez para iniciar revisiones de código cada vez que uno de nosotros registra algo. Solo somos 3, y cada uno de nosotros es alentado a revisar el código y dejar comentarios donde lo creamos conveniente.

Mi pregunta es, ¿cómo puedo dejar un comentario en una línea de código con la que veo un problema? Quiero expresar mi punto de vista sin parecer abrasivo.

No quiero parecer que estoy en un caballo alto y decir " Lo he estado haciendo de esta manera ... y tampoco quiero parecer que estoy tratando de ser autoritario y decir algo como " Esto debería hacerse de esta manera ... " pero todavía necesito dejar claro que lo que están haciendo no es muy bueno.

Para aclarar: Este es un recurso realmente bueno para lo que debería buscar comentar: ¿Es una revisión de código subjetiva u objetiva (cuantificable)? , pero estoy buscando cómo comentarlo.

Bueno, tiendo a hacer comentarios en varias áreas generales y cada tipo puede tratarse de manera diferente.

Cambios requeridos Estos son los tipos de cambios en los que señalo que el código no cumple con los requisitos funcionales o no funciona y debe arreglarse antes de ser enviado a producción. Tiendo a ser muy directo en estos comentarios. Los requisitos dicen ..., esto no hace eso. O esto fallará si el valor enviado es nulo (especialmente cuando sabe que ese caso ocurrirá en función de los datos que se enviarán).

Luego están los comentarios "esto funciona pero aquí hay una mejor manera de lograrlo". Tienes que ser más gentil en esto y hacer más de un argumento de venta. Podría decir que haría esto en su lugar porque es probable que tenga un mejor rendimiento (generalmente reviso el código SQL donde el rendimiento es muy importante). Podría agregar algunos detalles sobre por qué es una mejor opción, tal como lo haría al responder una pregunta sobre Stack Overflow. Podría señalar que no es necesario cambiar esto para este código en particular, sino considerar el cambio en la codificación futura. Básicamente con este tipo de comentarios, estoy educando a personas con menos experiencia sobre lo que podría funcionar mejor.

Luego están los comentarios "esto funciona pero hacemos las cosas de esta manera". Estos probablemente también serán cambios necesarios. Esto incluiría comentarios sobre los estándares de la compañía o la arquitectura que esperamos que usen. Haría referencia al documento estándar o de arquitectura y les diría que lo arreglen. El comentario sería sencillo pero neutral, falta así o no, o los nombres de las variables no se ajustan a nuestro estándar de nomenclatura o cosas similares. Por ejemplo, nuestra arquitectura para paquetes SSIS requiere que el paquete use nuestra base de datos de metadatos para almacenar información particular sobre el paquete y requiere un registro particular. El paquete funcionaría sin estas cosas, pero son necesarias por razones de la compañía (por ejemplo, necesitamos informar sobre la tasa de éxito de las importaciones o analizar los tipos de errores que recibimos).

Lo único que no desea hacer en los comentarios de revisión de código es atacar personalmente a alguien. También puede ayudar si encuentra algo que hicieron bien y señala que fue bueno. A veces aprendo algo nuevo de una revisión de código y, si lo hago, se lo digo a la persona.

Si el código sigue sus estándares de codificación, pero lo haría de una manera diferente, debe preguntarse si lo que hicieron está mal.

Si no es así ... simplemente no es como lo habría hecho y simplemente no puede dejarlo, intente simplemente preguntando '¿Por qué lo hiciste de esta manera en lugar de hacerlo de esa manera?' Luego, logrará que califiquen por qué lo hicieron de la manera en que lo hicieron sin decir 'Lo habría hecho de esta manera y tú también deberías ...'

También puede aprender algo en el proceso.

Quiero expresar mi punto de vista sin parecer abrasivo.

No confundas la terquedad con ser abrasivo. Cuando algo es un problema, documente de una manera que pueda entender quien lo va a arreglar. Apéguese a los hechos y no escriba un ensayo. Esto es:

• Esto hará que el frobnitz no funcione correctamente cuando el fooble esté a 5 grimbles del factor snorgatz.

• La convención establecida para hacer esto es llamar a fazzatz () con un Squidge recién inicializado. Convierta esto en un método para que siempre suceda de la misma manera y no se duplique.

  Tampoco quiero parecer que estoy tratando de ser autoritario y decir algo como "Esto debería hacerse de esta manera ..." pero todavía necesito dejar claro que lo que están haciendo no es muy bueno .

El propósito de revisar el código es poner un segundo par de ojos, generalmente más experimentados, para descubrir problemas. Si está en posición de emitir un juicio sobre el trabajo de otros y hay una razón válida para decir que algo no es bueno, estaría ignorando su responsabilidad como revisor si no lo hiciera.

Habrá desacuerdos, y esas son oportunidades para el revisor y el revisor para defender sus posiciones. Si de lo contrario eres compañero y llegas a un punto muerto, busca a alguien mayor para romper el empate.

Depende de qué tipo de problema se haya notado

• Falta el aviso de copywrite: un problema común y aburrido, solo un breve comentario que indica el problema y continúa
• lugares donde podría hacerlo de manera diferente: por lo general, tienden a hacer preguntas aquí en lugar de hacer declaraciones, a veces las respuestas justificarán la solución original otras veces no y luego puedo abordarlas de manera más explícita
• lugares donde hay un defecto claro, por ejemplo, Equivale a anulación que puede acumular desbordamiento - alcanzar el bolígrafo rojo - marcarlo como un defecto y ser muy explícito por qué está roto - también verifique otras áreas similares para verificar que no haya habido un problema sistemático.

Por mi experiencia:

1. Siempre tenga al autor del código con usted mientras revisa su código. Preferiblemente, el código se proyecta en la pizarra y ambos pueden ver claramente el código muy bien.

2. Ten una conversación amigable. Aprecio la buena parte de la codificación. Dígale que "esto es lo mejor que he visto" si ve algunas partes buenas en el código.

3. Pídale que revise su código y acepte y acepte los puntos válidos y lo corrija. Respete sus comentarios en su código y él respetará automáticamente sus comentarios de revisión de código.
4. Trate a nivel de desarrollador a menos que sea muy importante o se necesite más tiempo para corregir los problemas de revisión de código. No escale a los gerentes por problemas simples si faltan condiciones.
5. Mire con la perspectiva de "Aprender de otro código" en lugar de señalar errores en el código.
6. Durante las sesiones de revisión de código, cite los errores pasados ​​que cometió y cómo las revisiones de código lo ayudaron y evitaron grandes problemas de producción porque otro par de ojos lo ayudaron.
7. Se humilde. Más agradecimiento y menos comentarios para él :) Aprenderá mucho durante la revisión del código y él también estará encantado de aceptar sus comentarios.