Buenas prácticas en la revisión del código

El autor se benefician de obtener una perspectiva diferente de su tarea y código. A menudo aprenderán nuevos trucos o descubrirán una forma potencialmente más óptima de resolver un determinado problema. También desplegarán su conjunto de cambios con confianza, sabiendo que otras personas han comprobado que el código es correcto y están de acuerdo en que todo va bien.

El revisor se beneficiarán de ver en acción distintos enfoques de la resolución de problemas. También mejorarán su destreza en la lectura de código, lo que es muy importante a la hora de sumergirse, por ejemplo, en una biblioteca que está siendo evaluada para su uso en una proyecto. La revisión del código es también una oportunidad de aprendizaje tanto para el revisor como para el autor: ellos también pueden aprender nuevos trucos.

En equipo en su conjunto se beneficia, ya que la revisión de una solución a un determinado problema requiere comprender el problema al menos a un alto nivel de abstracción. Esto ayuda a derribar cualquier silo de conocimiento accidental que pueda producirse en un equipo. También aumentará el "factor autobús": como al menos dos personas (preferiblemente más) están al tanto de un cambio determinado, hay menos probabilidades de que se produzca una situación en la que nadie del equipo sepa cómo actualizar un módulo o por qué puede estar ocurriendo un determinado error.

El cliente se beneficia de cambios y soluciones desplegados con rapidez y confianza. Junto con otras buenas prácticas (como una gran cobertura de pruebas, CI/CD, entornos de preparación, etc.), las revisiones del código también garantizan que lo que se despliega es seguro, sano y cumple los requisitos especificados.

Finalidad y uso de estas directrices

Recuerde que, por encima de todo, estas sugerencias pretenden crear un entorno propicio para la resolución ambiciosa y eficaz de los problemas y, al mismo tiempo, crear una red de seguridad y fomentar la confianza y la transparencia en todos los miembros del equipo.

Aunque se recomienda encarecidamente que los equipos sigan estas directrices, no se pretende que sean normas rígidas. Este marco tampoco pretende ser un "proceso" que deba seguirse al pie de la letra, ya que los procesos rígidos tienden a reducir la velocidad y a fomentar el despilfarro.

Usted es más que bienvenido a construir sobre estas directrices dentro de su equipo. Recuerde, sin embargo, que a medida que los desarrolladores rotan entre equipos, esperarán que la revisión de código en cualquier equipo al que se unan siga basándose en este documento. Mantenga documentadas todas las normas adicionales y aporte a este documento las mejoras que hayan funcionado excepcionalmente bien.

Responsabilidades en torno a la revisión del código

Todos los miembros del equipo tienen ciertas responsabilidades con respecto a la revisión del código. A continuación se exponen algunos consejos sobre lo que se debe y no se debe hacer en la revisión del código, en función de la función que se desempeñe en el proceso.

Jefe de proyecto

• DO asegúrese de que sus repositorios están bien configurados (por ejemplo, no se permiten fusiones a su rama orientada a producción sin al menos una revisión de aprobación).
• DO Asegúrese de que su equipo entiende y aplica estas prácticas, y trabaje activamente para promover la comprensión de por qué hacemos las cosas de determinada manera.
• DO Esté atento a cualquier situación de empate en la que no puedan resolverse opiniones opuestas: como responsable técnico de su equipo, es su responsabilidad elegir la solución más pertinente en estos casos y hacer que el trabajo siga avanzando.
• Sin embargo, NO utilizar la dirección de proyectos como un instrumento contundente. NO "tirar de rango". DO acogerá con agrado la revisión y la crítica de sus soluciones tanto como las alienta sobre el trabajo de cualquier persona.
• CONSIDERA añadir una integración de GitHub al canal de Slack de tu equipo. Puede ser útil para poner mejor las solicitudes de revisión en el radar de los revisores, pero dependiendo del volumen general de tu canal, puede ser o no adecuado para tu equipo.

Miembro del equipo

• Participe en las revisiones del código. No es aceptable no revisar el código.
• Recuerda hacer tus revisiones de código: ¡tus compañeros de equipo dependen de ti para avanzar en su trabajo!
• Si no puede hacer absolutamente ninguna revisión, DO comunicarlo clara y abiertamente.
• Sin embargo, NO asumir que no puedes hacer una determinada revisión porque no conoces ese módulo/parte del sistema/especificaciones de lógica de negocio. La revisión del código es una importante oportunidad de aprendizaje.
• Si crees que no sabes lo suficiente sobre algo como para hacer una reseña, DO pregúntele al autor: estará encantado de explicarle lo que deben hacer los cambios.
• NO denegar revisiones en función del nivel de experiencia (la suya o del autor).
• DO Intenta revisar al menos tantos PR como produzcas. Lo ideal es que la proporción entre revisiones realizadas y revisiones necesarias sea superior a 1 (sobre todo en equipos grandes).

Autor

• DO Entienda que es su responsabilidad que su código sea revisado - su equipo puede estar buscando proactivamente pull requests para revisar, pero no tienen por qué hacerlo.
• NO asigne/solicite siempre revisiones a los mismos miembros del equipo: se beneficiará más de un grupo variado de revisores (y, a la inversa, una gama más amplia de desarrolladores se beneficiará de la revisión de su código).
• NO excluir a alguien de la revisión en función de su experiencia. Los desarrolladores junior se benefician de revisar el código. Los desarrolladores senior se benefician de la revisión del código. Como se indica en el prefacio de este documento, todo el mundo se beneficia de la revisión del código.
• CONSIDERA utilizando un aleatorizador para seleccionar a los revisores. Por ejemplo, en Ruby, %w[compañero1 compañero2 compañero3].sample puede hacer maravillas.
• DO asigna al menos dos revisores a tus pull requests, a menos que sea absolutamente imposible. De ese modo, más personas se benefician del proceso (y con tres personas es más difícil llegar a un empate).
• DO Sé receptivo en tus pull requests. Aunque no debería interrumpir su flujo para responder en este mismo instante a cualquier comentario, asegúrese de que sus respuestas sean oportunas; de lo contrario, sus PR se quedarán en revisión de código indefinidamente.
• DO Aporte una actitud abierta. Asume siempre que tu revisor está intentando ayudar con las mejores intenciones. Explica tu lógica, aborda los argumentos de tu revisor y responde a sus preguntas.
• DO Sé educado. Los malentendidos ocurren, pero no tienen por qué descontrolarse y dañar el ambiente del equipo.
• DO Sea honesto. Si cree que es la mejor solución, dígalo y presente sus argumentos. Si te convences de que las sugerencias de tu revisor son mejores que las que tú has producido, díselo. Si crees que se puede producir una solución "lo mejor de ambos mundos" utilizando tanto tus ideas como las de tu revisor, propónselo. En última instancia, trabaja para llegar a un consenso en tus pull requests.
• DO Deje la resolución de sus comentarios en manos de su revisor; no se limite a resolverlos porque esté convencido de que ya está bien.
• DO Explique activamente su tarea, su razonamiento y otros requisitos a sus revisores. Está bien no saber, pero no es aceptable ocultar información.
• NO suponer que lo sabes todo: todos somos especialistas increíbles, pero es importante aportar una cierta dosis de humildad al trabajo.
• DO ser el primer revisor de tu código. Ponte un sombrero de revisor y escanea el código con cuidado, como harías con la persona que menos te gusta. Identifica y elimina las cosas más obvias, como las líneas vacías, lo que sobra o las especificaciones que faltan. No te saltes nada: lo más probable es que te lo señalen de todos modos. No hagas perder el tiempo a los revisores.
• DO Describa a fondo su pull request. La descripción es buena cuando el revisor no se sorprende de nada al leer el código. Recuerde que no puede leer su mente. Por eso es importante describir las cosas que no son obvias, las decisiones clave con la razón o todas las nuevas clases y archivos.
• CONSIDERA utilizando la plantilla pull request. Si utiliza Github, añádalo a su repositorio en .github/pull_request_template.md. Anima a todos los miembros del equipo a describir sus pull requests. También es mucho más fácil escribir cuando tienes el campo de descripción rellenado con una plantilla. Aquí puedes encontrar una plantilla que utilizamos en uno de nuestros proyectos https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Autor

• DO entienda que es su responsabilidad revisión del código - Puede que tu equipo busque proactivamente pull requests para revisar, pero no tienen por qué hacerlo.
• NO asignar/solicitar revisiones siempre al mismo revisores de código - se beneficiará más de un grupo variado de revisores (y a la inversa, un abanico más amplio de desarrolladores se beneficiará de la revisión de su código)
• NO excluir a alguien de la revisión en función de su experiencia. Los desarrolladores junior se benefician de realizar revisiones de código. Los desarrolladores sénior se benefician de revisiones de código. Como se indica en el prefacio de este documento, todo el mundo beneficios de realizar revisiones de código.

Revisor

• DO utilizar el lenguaje de la sugerencia en lugar del de la exigencia. En lugar de decir "Deberías mejorar la calidad del código haciendo X en su lugar"., digamos "¿Has considerado mejorar calidad del código haciendo X?"
• DO explique sus sugerencias. "Creo que X es mejor aquí porque ayuda en transferencia de conocimientos y mejorar la calidad del código."
• Aunque su sugerencia proceda de fuentes objetivas (p. ej. estilo de código directrices), DO pedir al autor que haga algo en lugar de decirle que haga algo. "Por favor, mantenga todos los widgets frobnicated según nuestro estilo de código guía - [enlace]"
• NO asume que lo sabes todo. "Tengo entendido que este widget nunca debe frobnicarse, y en estas condiciones lo hará - ¿es esta una excepción que necesita un revisión del código?"
• DO utilizar un lenguaje inclusivo. "Creo que nos iría mejor en el futuro si construyéramos esto así. ¿Qué opinas de este mejor revisión del código ¿Sugerencia?" y "Tal vez deberíamos utilizar X aquí en lugar de un revisión eficaz del código?"
• DO sea puntual en hacer sus revisiones de código. No debes interrumpir tu ritmo de trabajo para hacerlos, pero intenta mantener el bucle apretado si es posible. A algunas personas les gusta hacerlos al principio o al final de su jornada laboral, como "calentamiento" o "enfriamiento".

Tenga en cuenta que estas palabras clave se han insertado de forma que se mantenga intacto el contexto y la coherencia del texto. Si las desea en algún lugar concreto, por favor, especifíquelo.