Por favor, mantengan simples las descripciones del código

• En una revisión de código, cuando llegan juntas explicaciones largas y un diff grande, al revisor le cuesta identificar la razón del cambio, por lo que los mensajes de commit, la descripción del merge request y los comentarios deben ser concisos
• Las explicaciones deben enfocarse más en por qué cambió algo que en qué cambió, ya que muchos cambios pueden verificarse en el propio código
• Las explicaciones largas que intentan meter todo el contexto de una sola vez pueden reducir la concentración y la velocidad de revisión de algunas personas revisoras
• En la revisión de merge, los commits atómicos son especialmente importantes, y los ajustes pequeños pueden manejarse con git amend, mientras que la limpieza antes de fusionar puede hacerse con rebase o squash
• Incluso si se usan herramientas de LLM, suele ser más útil escribir personalmente los comentarios, las explicaciones y los mensajes de commit para facilitar la comprensión del código y la accesibilidad de la revisión

---

En las explicaciones de revisión, enfócate en el “por qué” más que en el “qué”

• Si las explicaciones, los commits y los merge requests en una revisión de código están llenos de información excesiva, aumenta la carga de revisión
• Más que enumerar largamente qué cambió, lo importante es dejar claro por qué se hizo el cambio
• El propio código puede mostrar la mayor parte de los cambios, y si falta contexto, la persona revisora puede preguntar
• Las explicaciones escritas como textos largos pueden hacer más lenta la revisión para quienes tienen dificultades para mantener la concentración
• Conviene que los mensajes de commit, las descripciones de merge request y los comentarios en el código sean claros, directos y contengan solo la información necesaria

Solicitud sobre organización de commits y uso de LLM

• Los commits deben ser especialmente atómicos en la revisión de merge, y cada cambio debe poder entenderse de forma independiente
• Los ajustes pequeños pueden incorporarse con git amend, y antes de fusionar se pueden ordenar con rebase o hacer squash
• Incluso si se usan herramientas de LLM, se considera mejor redactar personalmente los comentarios, las explicaciones y los mensajes de commit
  • Escribirlos uno mismo ayuda a entender el contenido de los cambios
  • Las explicaciones redactadas directamente por quien hizo el cambio pueden ser más accesibles para la persona revisora
• También se incluye la opinión personal de que, si es posible, conviene evitar las herramientas de LLM
• Hubo reacciones a la expresión “accesibilidad”, pero la idea central es pedir que las explicaciones en las revisiones de código sean más concisas y más fáciles de revisar

[GN⁺]

Comentarios en Lobste.rs

• Hay que tener cuidado al equiparar requisitos de accesibilidad con preferencias personales específicas
  Tener ADHD no significa necesariamente que odiar mensajes de commit largos sea un rasgo universal del ADHD, y la accesibilidad no se trata de “hacer todo como le gusta a una persona con ADHD”, sino más bien de ajustes razonables que no impongan una carga excesiva al usuario general
  Por eso muchas funciones de accesibilidad están detrás de configuraciones que cada quien puede elegir, como alto contraste, reducción de movimiento y modo oscuro

  • Podría haberlo escrito con más claridad, pero mi AuDHD necesita ciertas condiciones para poder trabajar y funcionar bien
    Bloques largos de texto, por ejemplo cuando a un cambio pequeño le agregan una explicación del tamaño de dos páginas A4, pueden bloquearme por completo para trabajar, y si me obligo a leerlos puedo terminar en burnout
    Probablemente debería expresarlo como “esta es una necesidad de accesibilidad mía, y sé que hay muchas personas parecidas”
    Aun así, puede verse como una preferencia y no como una exigencia, pero es una petición para que, al pegar murallas de texto generadas por LLM en mensajes de commit, también tengan en cuenta a personas como yo
  • Depende de cada persona, pero eso de “ve al punto primero” me parece bastante un rasgo central del ADHD
    Incluso desde la accesibilidad, todos se benefician de ese ajuste, así que no parece haber razón para oponerse
  • En mi experiencia, muchas de las dificultades innecesarias que viven personas neurodivergentes y personas con discapacidad surgen de descartar las necesidades de accesibilidad como simples gustos
    Cuando la accesibilidad mejora, también se benefician quienes no necesitan estrictamente esa función para partir de una posición equivalente, así que avanzar en esa dirección me parece bueno

• Desde antes de la IA siempre he preferido comentarios excesivamente detallados, y a muchas personas con las que he trabajado eso les ha sorprendido
  Por ejemplo, está este método: https://github.com/ghostty-org/ghostty/…
  Durante los últimos 15 años, sin importar el lenguaje, en general he escrito con este estilo, y en la era de la IA incluso lo dejé especificado en AGENTS.md
  El archivo enlazado y todos los comentarios fueron escritos por una persona, sin usar nada de IA
  La razón es simple: obligan a cumplir una regla de doble registro en la que comentarios y código deben coincidir entre sí
  Si no coinciden, entonces el comentario está mal, o el código está mal, o ambos están mal, y tan solo preguntar “¿cuál de los dos está bien?” me ha ayudado a detectar muchos problemas
  Al final, si es tu proyecto, cada quien debería comentar como prefiera

  • A mí también a veces me hacen la broma amistosa de que escribo más comentarios que código, y realmente me encantan este tipo de comentarios
    Cuando vuelvo a leer el código más adelante, preservan el contexto de las decisiones locales que tomé en ese momento, y también ayudan a revisores o a alguien que lo ve por primera vez a construir contexto
    Estos comentarios son largos, sí, pero no son los “detalles innecesarios” de los que habla el texto, y el ejemplo compartido me parece un buen caso del consejo de “explica no qué, sino por qué”
  • Este tipo de comentarios son excelentes
    Como en el ejemplo, un comentario que explica por qué los usuarios de macOS terminan poniendo configuraciones del shell en ~/.bash_profile y esperan un login shell aporta contexto útil sobre por qué se tomó cierta decisión
    Pero volviendo a los LLM, personalmente todavía no he visto comentarios generados por LLM con esa calidad
    Normalmente se quedan en repetir cosas obvias que ya se entienden leyendo el código, como que hace foo(), luego hace bar(), y al final hace baz
  • El tipo de comentario enlazado no es problema
    El problema es el desastre de pegar tablas gigantes y listas con viñetas incluso en cambios diminutos
  • Agradezco mucho ese nivel de detalle, pero personalmente preferiría que estuviera en el mensaje de commit del commit que agregó ese método, más que en el comentario
    Siento que el mensaje de commit queda como un registro del mismo momento que el código, mientras que los comentarios pueden desalinearse con el tiempo
  • El comentario que empieza en la línea 1467 es una obra maestra; se le siente el cansancio

• En el trabajo intenté poner con cortesía en la plantilla de PR algo como “por favor explica directamente la motivación de este cambio y las decisiones de diseño importantes que hay que revisar”
  Pero 9 de cada 10 veces, el LLM que usan en ese momento se lleva por delante toda la plantilla y escupe una explicación larguísima, con el número de tests agregados, casillas de verificación de aprobados y tangentes largas sobre cosas triviales
  Así da muchísimo gusto revisar

  • En mi trabajo pasa lo mismo
    No sé quién pensó que era buena idea meter herramientas de mensajes de commit generados por LLM por todos lados, pero al final termina ocurriendo https://noslopgrenade.com/ dentro de los commits
    Los mensajes de commit o las descripciones de pull request ya no traen contexto útil como la motivación del cambio, decisiones de diseño o justificación, sino párrafos que desarrollan detalles de implementación que se entienden solo con leer el código
  • Yo también he visto ese comportamiento
    Estoy pensando en agregar a agents.md una indicación de que, al escribir mensajes de commit, se consulte commit-messages.md
    En commit-messages.md se podrían poner lineamientos para mensajes de commit, como prohibir casillas de tests aprobados/fallidos y resumir las pruebas individuales o simplemente no ponerlas

• Las veces en que escribo comentarios sobre qué estoy haciendo no son cuando explico por qué, sino cuando no estoy seguro de si esa forma es correcta
  Un origen clásico de sufrimiento repetido son las expresiones regulares

  • A mí me pasa igual
    Hay momentos en que sí hace falta explicar todo con solidez, pero últimamente veo explicaciones gigantes incluso en cambios pequeños como renombrar variables

• Curiosamente, a mí más bien me han dicho muchas veces que mis mensajes de commit son demasiado cortos

  • La discusión de este texto queda al lado del caso contrario, es decir, la queja de que las explicaciones son demasiado cortas en el texto Chesterton middle finger
  • Pueden ser demasiado cortos, sí, pero tampoco tiene sentido meter ahí toda una novela
  • Los LLM de verdad escriben demasiado
    Por eso configuré claude para que nunca escriba comentarios, porque yo terminaba borrando manualmente el 98% y reescribiendo incluso el 2% restante

• Normalmente me gustan los mensajes de commit muy explicativos, pero prefiero una estructura tipo artículo de noticias, donde la información más importante va primero y los detalles menos importantes, aunque todavía relevantes, van después
  Por ejemplo, en el título pongo la información más importante con la mayor densidad posible; en el primer párrafo explico los cambios con frases menos comprimidas; y en los párrafos posteriores dejo detalles adicionales sobre la naturaleza del cambio en el código que no hace falta leer con atención a menos que de verdad sea difícil entenderlo
  Creo que se subestima lo importantes que son los mensajes de commit para la gente que leerá el código en el futuro
  Cuando uno está excavando en el codebase y se pregunta por qué cierto bloque quedó así, nunca me ha decepcionado llegar con git blame a un mensaje de commit que explica con un nivel brutal de detalle que ese enfoque que parece torpe en realidad fue la opción que quedó después de varios intentos mejores en apariencia, pero incompletos
  Volviendo al punto del autor, poner señales explícitas en la comunicación es un buen ajuste y, en general, útil
  Puedes poner una frase a mitad del mensaje de commit como: “si estás revisando este código, puedes dejar de leer aquí”

• Decir “los detalles innecesarios se pueden preguntar si hacen falta” asume con bastante audacia que esa persona va a seguir ahí
  Empecé a escribir mensajes de commit con mucho cuidado al empezar a contribuir a un codebase FLOSS de más de 10 años
  La única forma de averiguar más sobre por qué el código existía así era la arqueología de git, y aprendí a usar vc-annonate de Emacs para rastrearlo fácilmente
  Incluso en código del trabajo, varias veces el autor original del codebase que yo mantenía ya se había ido hacía mucho tiempo
  Los mensajes de commit no se leen solo durante la revisión; de hecho, muchas interfaces de revisión hasta los ocultan
  El problema parece estar menos en los mensajes de commit largos en sí y más en los mensajes de commit mal escritos
  Una guía como “los mensajes de commit, las descripciones de merge request y los comentarios de código deben ser claros, ir al grano según la necesidad y explicar no el qué sino el porqué” suena bien
  También puede pasar que alguien que antes solo escribía Fix Bugz 🚀️ ahora, diciendo que seguirá las “mejores prácticas”, use un LLM para redactar mensajes de commit
  Mi hipótesis es que la mayoría no escribe mensajes de commit porque no los lee, y no los lee porque la energía de activación para buscarlos es alta cuando dependes de lugares como la interfaz web de GitHub para recorrer los commits

  • “Los detalles innecesarios se pueden preguntar si hacen falta” se refiere a la revisión
    Si la información es importante, puede dejarse como comentario o añadirse al mensaje de commit
    KDE usa Gitlab desde hace algunos años

• A largo plazo, para una arqueología de git exitosa para quienes vengan después, hace falta equilibrio
  Muchas veces no se puede preguntar después por esos detalles que parecían innecesarios, por cambios de personal o porque el contexto desaparece de la cabeza de la gente
  El mejor momento para registrar ese contexto es cuando todavía lo tienes
  Tal vez lo que realmente queremos es poner primero los detalles importantes y diferenciarlos con claridad, como en un resumen

• Los PR o las explicaciones del código no son para qué hiciste, sino para por qué lo hiciste
  Deben decir por qué el código tiene esta forma y cuál es la razón detrás
  Eso sirve para la revisión y también para encontrar después, en el historial de git, por qué el código terminó siendo así

• Mantener simples las explicaciones del código es importante
  Porque no se puede leer algo que no puedes entender o en lo que no puedes concentrarte
  Al mismo tiempo, al desarrollar software se pierde mucho contexto, y ahora mismo ese contexto muchas veces solo está en la cabeza del autor, de quien habló con él o de quien miró el código a fondo
  Pero creo que ese contexto debería estar más entrelazado con el código, no menos
  Como no siempre puedes hablar con el autor, hay que dejarlo escrito en un lugar siempre accesible y que se actualice junto con el código
  En la mayoría de los flujos de desarrollo actuales, el lugar más adecuado para eso es el mensaje de commit de git
  Está bien poner un resumen arriba, pero también recomiendo dejar explicación adicional sobre el cambio en el código
  Si externalizas el contexto, incluso el que ahora no parece importante, tu yo del futuro te lo va a agradecer
  Hacia adelante, hace falta un enfoque mejor que poner ese contexto solo en los mensajes de commit, y por eso personalmente me gusta la programación literaria, que da más espacio para explicar el “qué” y el “porqué” del código