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

13

Mi equipo acaba de comenzar a usar crisol / ojo de pez para iniciar las revisiones del código cada vez que uno de nosotros comprueba algo. Solo somos 3, y todos estamos animados a revisar el código y dejar los comentarios donde nos parezca oportuno.

Mi pregunta es, ¿cuál es la mejor forma de 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 tengo que aclarar qué. Lo que están haciendo no es muy bueno.

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

    
pregunta stinkycheeseman 29.03.2012 - 15:41

5 respuestas

8

Bueno, tiendo a hacer comentarios en varias áreas generales y cada tipo podría manejarse 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 que no funciona y debe solucionarse antes de pasar 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 se producirá 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 amable con estos 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, como lo haría para responder una pregunta sobre el desbordamiento de pila. 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 las personas con menos experiencia en lo que podría funcionar mejor.

Luego están los comentarios de "esto funciona pero nosotros hacemos las cosas de esta manera". Estos probablemente también serán necesarios cambios. Estos incluirían comentarios sobre los estándares de la compañía o la arquitectura que esperamos que usen. Me referiría a la norma o al documento de arquitectura y les diría que se ajusten a la norma. El comentario sería sencillo pero neutral, falta así y los nombres de las variables no se ajustan a nuestro estándar de denominación 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 se requieren por razones de la empresa (debemos informar el índice de éxito de las importaciones, por ejemplo, o analizar los tipos de errores que recibimos).

Lo único que no quieres 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 hice, se lo digo a la persona.

    
respondido por el HLGEM 29.03.2012 - 16:10
6

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

Si no lo es ... no es cómo lo habrías hecho y no puedes dejarlo, intenta preguntar: "¿Por qué lo hiciste de esta manera en lugar de hacerlo de esa manera?" Entonces los está haciendo calificar por qué lo hicieron de la manera en que lo hicieron sin decir "Lo habría hecho de esta manera y usted también debería ..."

También puedes aprender algo en el proceso.

    
respondido por el Tyanna 29.03.2012 - 16:09
4
  

Quiero transmitir mi punto sin parecer   abrasivo.

No confundas la terseness con ser abrasivo. Cuando algo sea un problema, documéntelo de manera que quien lo arregle pueda entenderlo. Apégate a los hechos y no escribas un ensayo. A saber:

  • Esto causará que frobnitz funcione mal cuando fooble se encuentre dentro de los 5 gestos 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 diga algo como "Esto debería hacerse de esta manera ..." pero   Todavía tengo que entender que lo que están haciendo es   no muy bien.

El propósito de revisar el código es poner un segundo par de ojos, generalmente más experimentados, en él para descubrir problemas. Si estás en la posición de juzgar el trabajo de otros y hay una razón válida para decir que algo no está bien, estarías descuidando tu responsabilidad como crítico si no lo hicieras.

Habrá desacuerdos, y esas son oportunidades para que el revisor y el revisor defiendan sus posiciones. Si de lo contrario, son compañeros y llegan a un punto muerto, busque a alguien mayor para romper el empate.

    
respondido por el Blrfl 29.03.2012 - 17:58
3

Depende de qué tipo de problema se haya notado

  • aviso de copywrite faltante: un problema común y aburrido, solo un breve comentario que indica el problema y sigue adelante
  • lugares donde podría hacerlo de manera diferente; generalmente tiendo a hacer preguntas aquí en lugar de hacer declaraciones, a veces las respuestas justifican la solución original otras veces, y luego puedo abordarlas de manera más explícita
  • lugares donde hay un defecto claro, por ej. Igual a la anulación que puede apilar el flujo: alcanzar el lápiz 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.
respondido por el jk. 29.03.2012 - 16:14
1

Desde 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 claramente puede ver el código muy bien.

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

  3. Pídale que revise su código y acepte y acepte la validez.     Puntos y corregirlo. Respeta sus comentarios en tu código.     y él automáticamente respetará tus comentarios de revisión de código.
  4. Trate con el nivel de desarrollador a menos que sea muy importante o     Se necesita más tiempo para corregir los problemas de revisión de código. No escalar a     gerentes para problemas simples si faltan condiciones.
  5. Mira con la perspectiva de "Aprender de otro código" en su lugar     de señalar errores en el código.
  6. Durante las sesiones de revisión de código, cite los errores pasados que     Han hecho y cómo las revisiones de código le ayudaron y evitaron la gran producción.     problemas porque otro par de ojos te ayudó.
  7. Sé humilde. Más aprecio y menos comentarios para él :)     aprender mucho durante la revisión del código y él también con gusto aceptará su     comentarios.
respondido por el java_mouse 29.03.2012 - 18:14

Lea otras preguntas en las etiquetas