𝗢𝗽𝗲𝗻 𝘁𝗵𝗲 𝗣𝗥 𝘆𝗼𝘂𝗿 𝗿𝗲𝘃𝗶𝗲𝘄𝗲𝗿 𝗵𝗮𝘀 𝗻𝗼𝘁 𝗺𝗲𝘁 𝘆𝗲𝘁
I reviewed a large pull request recently. It used AI to help write the code. It changed a module that three other features used. The description was only one sentence. It named the file but not the reason for the change.
I spent fifteen minutes mapping the changes before I could start. I had to find the intent. I had to find the risks. I had to separate the important files from the noise.
I realized I had done this to someone else before.
When you write code, you carry all the context. You know why you split a module. You know what you tried first. You know which parts you feel unsure about.
Most people write descriptions for themselves. They write "Refactored service layer" or "Fixed auth module." These are descriptions for people who already know the context.
A good description is for the person who knows nothing.
A description is not just a summary. It is a test. If you cannot explain your work, your work is not ready.
I now use a six-part structure for every non-trivial PR:
• Intent: Explain why this PR exists and the problem it solves. If you cannot write this, stop. The PR is not ready. • Major changes: List decisions that affect architecture or existing behavior. • Minor changes: List cleanups and renames. Keep them separate from structural changes. • Impact: List the systems this touches. Provide a map of the blast radius. • Evidence: List what you ran and what tests you passed. Show proof that you did the work. • Uncertainties: State what you are unsure about.
When you admit uncertainty, you help the reviewer. They know where to look closely. They do not waste time on parts that are working fine.
If you cannot name your uncertainties, you have not thought deeply enough about your code.
The description is the last step before you decide if a PR should even open.
A reviewer who understands your intent spends time on hard questions. A reviewer who must guess your intent spends time on easy questions. They ask what things are instead of asking if they are right.
Write for the reviewer who has not met your code yet. Write as if you will not be there to answer questions. Write as if you are reading it three days from now with no memory of the work.
If the description holds up, the PR is ready.
Abre el PR, tu revisor aún no te conoce
Todos hemos pasado por esto. Has estado trabajando en una funcionalidad durante días, tal vez semanas. Has escrito cientos de líneas de código, implementado lógica compleja y, finalmente, te sientes listo. Creas un Pull Request (PR), añades una descripción y esperas a que ocurra la magia. Pero entonces, la realidad te golpea.
Tu revisor abre el PR y se encuentra con una montaña de cambios. De repente, el entusiasmo desaparece y es reemplazado por la fatiga de revisión. El proceso se ralentiza, los comentarios se vuelven superficiales o, peor aún, el PR se queda estancado durante días.
El problema del "Big Bang" PR
El "Big Bang" PR ocurre cuando intentas enviar una cantidad masiva de cambios de una sola vez. Es como intentar que alguien lea un libro entero y te dé su opinión en un solo día. Es abrumador, propenso a errores y difícil de procesar.
Los PRs gigantes tienen varios problemas:
- Carga cognitiva alta: El revisor tiene que mantener demasiada información en su cabeza a la vez.
- Revisiones superficiales: Ante la magnitud del cambio, es fácil que el revisor pase por alto errores críticos.
- Conflictos de fusión masivos: Cuanto más tiempo pase un PR abierto sin ser revisado, más probable es que haya conflictos con la rama principal.
Por qué deberías abrir los PRs temprano
Aquí es donde entra el consejo: Abre el PR antes de que esté terminado.
No significa que debas enviar código incompleto y esperar que lo fusionen de inmediato. Significa que debes dar visibilidad a tu trabajo desde el principio.
Los beneficios de los PRs tempranos
- Feedback temprano: Obtener comentarios sobre la arquitectura o la dirección de tu código antes de que hayas invertido demasiado tiempo en un enfoque equivocado.
- Reducción del retrabajo: Es mucho más fácil cambiar una dirección cuando solo has escrito 50 líneas de código que cuando has escrito 500.
- Mejor comunicación: Permite que tu equipo sepa en qué estás trabajando y evita que dos personas trabajen en la misma cosa de formas distintas.
- Revisiones más rápidas: Los PRs más pequeños y frecuentes son mucho más fáciles de revisar y aprobar.
Cómo hacerlo correctamente: Los Draft PRs
La mejor manera de implementar esto es utilizando Draft Pull Requests (PRs en borrador).
La mayoría de las plataformas como GitHub y GitLab tienen esta funcionalidad. Un Draft PR le indica a tus compañeros: "Estoy trabajando en esto, no lo fusionen todavía, pero me encantaría recibir comentarios sobre la dirección que estoy tomando".
Consejos para usar Draft PRs:
- Sé claro en la descripción: Explica qué estás intentando lograr y qué partes están terminadas y cuáles no.
- Pide feedback específico: En lugar de decir "revisa esto", di "¿qué piensas de la estructura de esta clase?" o "¿crees que este enfoque es escalable?".
- Mantén los cambios incrementales: Intenta dividir tu funcionalidad en piezas más pequeñas y manejables.
Conclusión
No esperes a que tu código sea perfecto para mostrarlo. Al abrir tus PRs temprano, no solo mejoras la calidad de tu código, sino que también construyes una cultura de colaboración y transparencia en tu equipo.
Recuerda: Tu revisor no es un juez que espera a que cometas un error; es un compañero que quiere ayudarte a tener éxito. ¡Abre ese PR!