En su blog The Old New Thing, el ingeniero de Microsoft Raymond Chen ha explicado la diferencia entre la descripción de una pull request y los comentarios integrados en el código fuente. La descripción del PR, afirma, es una declaración puntual que sirve a la propia revisión del código. Es un ejercicio de escritura persuasiva, porque su trabajo consiste en convencer al aprobador de que el cambio debe ser aceptado.

Los comentarios en el código cumplen otra función. Explican el propio código: cómo llamar a una función, qué requisitos previos se aplican y conocimientos similares. Chen califica esta información de duradera, ya que sigue siendo útil mucho después de que la pull request se haya fusionado.

The Register añade que los mensajes de commit probablemente también merecen un lugar en el debate. El tema llega en un momento en que las herramientas de codificación con IA generan grandes volúmenes de pull requests, junto con anotaciones de calidad a veces cuestionable. El artículo recuerda extremos antiguos de la cultura de los comentarios, desde un colega cuyos comentarios de C++ consistían sobre todo en disculpas a los futuros mantenedores, hasta otro que se negaba a anotar nada alegando que el código se autodocumentaba. Una anotación moderna más honesta, sugiere el autor, podría decir: escrito por algún asistente de codificación, y nadie sabe cómo funciona todo esto.

El texto también conecta el debate con la eterna disputa entre tabulaciones y espacios. En 2024, otro veterano de Microsoft, Larry Osterman, sostuvo que las tabulaciones tenían sentido cuando el almacenamiento era escaso, pero que los espacios son hoy la opción más segura porque siempre funcionan y se mantienen coherentes. La postura de Chen sobre el formato es más liberal: le da igual cómo formatee cada uno su código fuente. Su único consejo práctico es registrar por separado cualquier reformateo general, para que los revisores no queden sepultados bajo un diff dominado por cambios de guía de estilo.

El cierre vuelve a la distinción central de Chen: la descripción del PR argumenta por qué un cambio merece ser aceptado, mientras que los comentarios del código preservan lo que los futuros programadores necesitan para entenderlo.