Como ingenieros de software, a veces nos centramos demasiado en escribir código y no exploramos los procesos que ayudan a mejorar la eficiencia individual y del equipo. Algunas mejoras de procesos llevan mucho tiempo, pero hay un cambio sencillo que puede marcar una gran diferencia: Crear pull requests que sean fáciles de revisar.
En este artículo ofreceremos algunas buenas prácticas sobre cómo hacerlo. Primero entraremos en detalle sobre cómo mejorar los RP puede mejorar la eficiencia y los resultados de un equipo y luego echaremos un vistazo a las mejores prácticas que han ayudado a DoorDash a mejorar nuestro ciclo de vida de desarrollo de software.
Por qué las malas relaciones públicas ralentizan el ciclo de desarrollo
Los malos PR dificultan la colaboración, lo que ralentiza el proceso de desarrollo. Cuando un RP es difícil de revisar, recibe menos comentarios y desacuerdos, lo que conduce a errores y a una degradación de la calidad del código. En conjunto, estos problemas son, en última instancia, mucho más costosos que conseguir el código correcto a la primera. Los errores crean experiencias negativas para el usuario o ralentizan la comercialización. La degradación de la calidad del código dificulta su desarrollo a largo plazo.
En el extremo, los malos RP pueden llevar a una revisión del estilo "marcar la casilla" en la que los ingenieros aprueban sin molestarse en leer el código. Una revisión negligente anula el propósito de crear un PR en primer lugar. El código desarrollado sin la colaboración adecuada también inhibe el crecimiento de los desarrolladores noveles, que necesitan comentarios atentos para aprender. Tener una cultura de revisión sólida puede ayudar a prevenir el estancamiento de las habilidades. A continuación describimos varias prácticas recomendadas para garantizar que los RP sean fáciles de revisar y cumplan su propósito de mejorar el proceso de desarrollo.
Manténgase informado con las actualizaciones semanales
Suscríbase a nuestro blog de ingeniería para recibir actualizaciones periódicas sobre los proyectos más interesantes en los que trabaja nuestro equipo.
Introduzca una dirección de correo electrónico válida.
Gracias por suscribirse.
Conceptos básicos de las relaciones públicas
Pónselo fácil a tus revisores escribiendo código que lo sea:
- Fácil de entender
- Bien estructurado y coherente con las normas de estilo
- Haciendo lo que se supone que debe hacer
- Para verificar el comportamiento correcto es necesario comprobar la cobertura de las pruebas y asegurarse de que se superan por las razones correctas.
Para ayudar a los equipos a mejorar su cultura de revisión, he aquí algunas directrices para gestionar la creación de relaciones públicas y los comentarios. Nos adentraremos en cada una de estas mejores prácticas: .
- Escriba nombres descriptivos y coherentes
- Crear un título y una descripción de relaciones públicas claros
- Los PR deben ser breves (lo mismo se aplica a los archivos y funciones).
- Gestionar los desacuerdos en materia de relaciones públicas mediante la comunicación directa
- Evite las reescrituras obteniendo retroalimentación desde el principio
- Solicitar revisores adicionales para crear diálogo
Escriba nombres descriptivos y coherentes
La nomenclatura de variables y funciones es uno de los mayores retos de la ingeniería de software.
Una mala nomenclatura conduce inevitablemente a errores y aumenta el tiempo que el revisor inicial debe dedicar a entender el código. Si la mala nomenclatura pasa la revisión del código, los problemas de errores no detectados y el aumento del tiempo necesario se multiplicarán para todos los ingenieros que interactúen con el código en el futuro. Por eso es fundamental elegir buenos nombres de variables desde el principio, para ahorrar tiempo y evitar dolores de cabeza a largo plazo.
Todos tenemos una idea de lo que son buenos y malos nombres. Por lo general, sólo es cuestión de invertir tiempo en debatir y elegir buenos nombres desde el principio.
He aquí algunos ejemplos:
// Bad
val cid;
// Good
val consumerId;
// Bad
val distance;
// Good
val distance_meters;Preste atención también al contexto más amplio de cómo se nombran otras cosas. Esta consideración se pasa por alto con demasiada frecuencia. Fuera de este contexto, los nombres pueden resultar incoherentes o sobrecargar su significado.
He aquí algunos ejemplos:
Nombres incoherentes
// Bad
Service A {
val doordash_id;
}
Service B {
val a_id; // doordash_id from Service A
val doordash_id; // doordash_id from Service B
}
// Good
Service A {
val doordash_id;
}
Service B {
val doordash_id; // doordash_id from Service A
}Mismo nombre, distinto significado
// Bad
fun function1() {
val color_code; // means hex code
}
fun function2() {
val color_code; // means the code column in the color table
}
// Better
fun function1() {
val color_hex_code; // means hex code
}
fun function2() {
val color_code_id; // means the code column in the color table
}
Para evitar confusiones, el nombre de una variable debe explicarse por sí mismo.
Es esencial utilizar una nomenclatura descriptiva y coherente para todo, a fin de evitar confundir al revisor. Esta es una de las áreas en las que el perfeccionismo merece la pena; incluso un caso de pereza o cansancio puede crear una confusión que derive en un error o en un revisor frustrado.
Una nomenclatura clara es crucial para la vida útil del código. Una vez que el código se fusiona, es probable que los nombres de las variables y funciones no cambien durante un tiempo. Una mala elección de nombres puede confundir fácilmente a más de 100 ingenieros en el transcurso de un par de años, pero una vez que el código se replica y se acepta, puede ser difícil cambiar cualquier nombre.
Crear un título y una descripción de relaciones públicas claros
Aunque mucha gente sólo piensa en el código cuando crea un RP, el contexto es esencial para entender y revisar ese RP.
Los revisores deben saber cuál es el problema fundamental antes de poder entender si se ha resuelto. No obligue a un revisor a leer 600 líneas de código. En su lugar, proporciona un título descriptivo del PR y un resumen de alto nivel en la parte superior del PR.
Por eso es una buena práctica crear y hacer cumplir el uso de plantillas de RR:
- Problema
- Solución
- Impacto
- Plan de pruebas
El uso de una plantilla proporciona a los revisores un contexto para que puedan ofrecer comentarios significativos sin tener que rebuscar en los documentos o el código. También puede ayudar a los revisores a detectar errores. Por ejemplo, si la descripción dice que el indicador de función está siempre desactivado, pueden buscar el indicador de función para confirmarlo.
Si estás empezando a utilizar plantillas de relaciones públicas, empieza con una plantilla realmente breve, porque ser conciso ayuda al revisor, lo que se traduce en mejores resultados. Esta entrada del blog de Axolo incluye un buen ejemplo de plantilla breve.
Los PR deben ser breves (al igual que los archivos y las funciones).
Hay un círculo vicioso que ocurre con los PR largos. Los RRPP largos generan tiempos de revisión largos, y los tiempos de revisión más largos generan RRPP más largos porque los ingenieros intentan que se revise más código por RRPP, repitiéndose el ciclo.
En realidad es mejor escribir RRPP cortos. Aunque las revisiones iniciales pueden seguir siendo lentas, los tiempos de revisión se acelerarán porque los PR más cortos son más fáciles de revisar.
Escribir PRs cortos requiere disciplina. Aunque se tenga la intención de escribir un RP corto, los RP se alargan después de escribir las pruebas y solucionar los casos extremos. A veces también se alargan, cuando el código relacionado con un PR anterior se refactoriza en el PR actual.
E incluso si estás comprometido con las relaciones públicas cortas, eso plantea la pregunta: ¿Cuánto tiempo es demasiado?
Algunos equipos prefieren establecer directrices numéricas, como menos de 400 líneas o menos de 10 archivos. Otros equipos prefieren dividir los RP en unidades lógicas, como el editor de eventos, el controlador o la capa de base de datos, en lugar de establecer directrices numéricas. Lo más importante es elegir un método y decidir cómo aplicarlo; los RP no se acortarán por arte de magia porque el equipo acuerde que es necesario hacerlo.
¿Por qué las relaciones públicas más cortas son mejores para el desarrollo?
- Un RP más corto conlleva menos errores y más comentarios por línea. Es mucho más fácil detectar errores en un RP más corto, mientras que un RP extremadamente largo tiene más probabilidades de obtener un "LGTM" (Looks Good To Me).
- Las revisiones son más rápidas. Los ingenieros pueden revisar un RP corto de 300 líneas en un hueco entre reuniones. Puede ser más difícil dedicar el tiempo necesario a revisar un RP de 600 líneas.
Gestionar los desacuerdos en materia de relaciones públicas mediante la comunicación directa
Como ingeniero recién graduado, me resulta difícil saber qué hacer cuando dos ingenieros veteranos discrepan sobre mi RP. También puede pasar mucho tiempo entre las respuestas en la sección de comentarios de GitHub.
En lugar de esperar a las idas y venidas, intenta iniciar una comunicación directa a través de Zoom o Slack en cuanto empiece la conversación. Actualiza después el comentario de GitHub para cerrar el círculo sobre lo que se ha decidido y por qué.
¿Por qué ayuda la comunicación directa?
- La respuesta será más rápida.
- La comunicación verbal da lugar a menos malentendidos.
- 10 minutos de comunicación verbal es una revisión mucho más exhaustiva que unos cuantos comentarios de ida y vuelta en GitHub.
- La conversación directa evita el constante cambio de contexto entre otros trabajos y la consulta de la sección de comentarios de relaciones públicas.
Evite las reescrituras obteniendo retroalimentación desde el principio
Como recién licenciada, a veces me cuesta decidir cuándo debo pedir ayuda. Aunque es mejor responder a algunas preguntas mediante la investigación o el método de ensayo y error, puede pagarse un precio muy alto por ir en la dirección equivocada durante demasiado tiempo. La información temprana suele ser más útil.
Para decidir si ha llegado el momento de pedir ayuda, prueba estos pasos:
- Averigüe la urgencia: si es urgente, pida información de inmediato.
- Antes de buscar una solución, asegúrese de formular la pregunta correcta.
- Puede ser difícil encontrar la respuesta a una pregunta muy concreta, pero mucho más fácil responder a una versión más amplia de esa pregunta.
- Por ejemplo, una pregunta concreta podría ser: "¿Cuál es el plural de PR (pull request)?". Pero una respuesta puede ser más fácil para la pregunta general: "¿Cómo funcionan las siglas en plural?".
- Buscar en Google, en el código base, en la documentación interna y/o en Slack.
- Prueba a depurar con el patito de goma (https://en.wikipedia.org/wiki/Rubber_duck_debugging)
- Aunque la tradicional "depuración del patito de goma" consiste en hablar en voz alta a un objeto inanimado, puede ser incluso más útil escribir el problema.
- Empieza resumiendo el problema y lo que has intentado hasta ahora, incluidas las posibles soluciones.
- Pedir ayuda
- Dile a la gente cuánto tiempo llevas atascado, qué has intentado y qué estás pensando.
- If it’s urgent, explain the urgency. If it’s a one-off request and not a pattern of behavior — and even if you should have asked earlier — people tend to be sympathetic to: “Hey, I’m sorry, I know I should’ve asked earlier, but I could really use your help because <reason>.” .
Una forma de obtener comentarios tempranos es crear un PR en "modo borrador", lo que impide que se fusione. Por lo general, los desarrolladores no solicitan una revisión antes de que su código esté funcionando, pero crear un borrador de PR para un esqueleto de código o incluso un código ligeramente defectuoso puede ayudar a solicitar comentarios útiles.
Una retroalimentación temprana permite corregir el rumbo con antelación, lo que ahorra tiempo a la hora de reescribir funciones y pruebas si algo va mal.
Solicitar revisores adicionales para crear diálogo
A veces queremos que nuestro código se fusione rápidamente, así que buscamos una aprobación en lugar de una revisión y un diálogo adecuados. Sin embargo, las revisiones superficiales frustran el propósito de la revisión del código.
Un paso que puede ayudar a abrir el diálogo es solicitar más revisores.
¿Por qué es útil solicitar más revisores?
- Añade más perspectivas. Si solo se requiere una aprobación y solo se solicita una revisión, los demás compañeros de equipo nunca tendrán la oportunidad de discrepar.
- Las personas están disponibles en diferentes momentos. Solicitar más revisores aumenta la probabilidad de que los ojos lleguen antes al RP.
- Si hay un desacuerdo más general sobre estilo de codificación/diseño en el PR, otros tienen la oportunidad de opinar o al menos darse cuenta de ello.
- Los standups son por naturaleza más actualizaciones de estado que trabajo en la maleza. Cuando alguien es requerido en un PR, puede leer exactamente en qué está trabajando un compañero de equipo y puede hacer referencia a ese código si se encuentra con un problema similar.
Conclusión
Escribir PR fáciles de revisar y mantener una cultura de revisión sólida es clave para una buena ingeniería de software. Los PR no solo sirven para que se apruebe el código, sino también para fomentar la retroalimentación y resolver desacuerdos.
Tanto si eres un becario que está aprendiendo cómo funciona el sector como si eres un ingeniero veterano que intenta dar buen ejemplo a su equipo, crear relaciones públicas limpias y gestionar bien los comentarios acelerará tu proceso. Crear este hábito dará sus frutos a largo plazo y garantizará que se sigan las buenas prácticas incluso en tiempos ajetreados. Tu futuro yo y tus futuros colegas te lo agradecerán.