En el desarrollo de software colaborativo, los pull requests ofrecen dos espacios distintos para documentar una cambio: la descripción del PR y los comentarios dentro del propio código. Cada uno cumple una función diferente y mezclarlos provoca confusión a medio y largo plazo.
La descripción del pull request es un mensaje puntual dirigido al revisor: justifica por qué el cambio es necesario, qué problema resuelve, por qué se eligió esa implementación frente a alternativas y qué validaciones se realizaron. Su valor es coyuntural, ligado al momento de la revisión, y puede incluir capturas comparativas, resultados de pruebas o enlaces a plantillas de check-in. Un buen título, además, ayuda a localizar el PR cuando alguien investiga una regresión meses después.
Los comentarios en el código, en cambio, son información duradera: explican cómo invocar correctamente una función, qué precondiciones requiere o por qué existe una decisión de diseño concreta. Deben entenderse de forma autónoma, sin necesidad de leer la descripción original del PR. Si un comentario solo tiene sentido durante la revisión, pertenece a la descripción; si seguirá siendo útil dentro de un año, pertenece al código.
El autor ilustra la diferencia con ejemplos reales: una nota que dice «he comprobado todas las llamadas a esta función y solo esta pasaba el flag incorrecto» justifica la corrección y caduca cuando alguien añada una nueva llamada, por lo que va en el PR. En cambio, «el esquema JSON aceptado por esta función está documentado aquí» es una guía de uso que permanecerá vigente, así que va en el código. Otro caso habitual: escribir «cuando todos los clientes migren a la nueva función, mantener esta» sobre la función nueva resulta críptico sin contexto; lo correcto es colocar «cuando todos los clientes hayan migrado, eliminar esta función» sobre la función antigua.