Casi nadie discute que la documentación hace falta, y casi nadie tiene ganas de escribirla un viernes a la tarde, con el pull request abierto y el cliente esperando. Ahí es donde un modelo de lenguaje rinde más de lo que uno espera: no porque entienda tu sistema mejor que vos, sino porque redactar a partir de algo que ya existe es una tarea en la que se defiende bien.
Docstrings y comentarios
Pasarle una función y pedirle un docstring suele dar un primer borrador razonable. Describe parámetros, valor de retorno y comportamiento general. El problema es lo que no ve: la regla de negocio que explica por qué la función redondea para abajo, el acuerdo con otro equipo, el bug histórico que motivó ese if raro.
Por eso conviene pedirle que documente qué hace y dejar el por qué para vos. Un docstring generado que dice "calcula el descuento aplicable" es correcto y casi inútil. Agregarle una línea tuya con la razón de fondo es lo que lo vuelve valioso dentro de un año.
def aplicar_descuento(total, categoria):
"""Devuelve el total con el descuento de la categoría.
Las categorías desconocidas no tienen descuento. El resultado
se redondea a dos decimales hacia abajo (pedido del área contable).
"""
La segunda frase del ejemplo es de una persona; la primera la puede escribir cualquiera, incluido un modelo.
README, changelogs y resúmenes de PR
Para un README el modelo sirve como armador de estructura: instalación, configuración, cómo correr los tests, cómo contribuir. Dale el árbol de archivos y los comandos reales del proyecto y vas a tener un esqueleto decente. Después tenés que ejecutar cada comando tal como quedó escrito. Los modelos inventan con soltura un script que nunca existió en tu package.json o en tu Makefile.
Con los changelogs pasa algo parecido. Si le pasás la lista de commits o el diff, agrupa cambios y redacta entradas legibles. Lo que no puede saber es cuáles rompen compatibilidad para quien usa tu librería, salvo que se lo digas. Esa clasificación es una decisión tuya.
Los resúmenes de pull request son quizá el uso más cómodo. Un diff grande se vuelve una descripción de tres párrafos que ayuda al revisor a ubicarse. Leelo antes de publicarlo: si el resumen omite un cambio o lo describe mal, el revisor va a confiar en una versión equivocada de lo que está mirando.
Revisión como segunda opinión
Pedirle a un modelo que revise un cambio puede atrapar cosas que a vos se te pasaron: una variable sin inicializar en una rama poco frecuente, un caso de lista vacía, una consulta dentro de un bucle, un manejo de errores que se traga la excepción. Es parecido a pedirle a un colega que le eche un vistazo rápido, con la diferencia de que no se cansa y no tiene vergüenza de preguntar lo obvio.
También tiene límites bien concretos:
- Ve lo que le mostrás. Si el bug está en cómo interactúa tu cambio con un módulo que no pegaste, no lo va a encontrar.
- Genera falsos positivos con total aplomo. Va a señalar como problema algo que tu framework ya resuelve, o proponer una "mejora" que cambia el comportamiento.
- No conoce las convenciones de tu equipo salvo que se las des.
Tratalo como una lista de sospechas para verificar, no como un veredicto. Cuando te marque algo, comprobalo: si tenía razón, corregís; si no, lo descartás en dos minutos. Lo que no conviene es aceptar la sugerencia sin entenderla, porque eso es exactamente lo que una revisión debería evitar.
Tampoco reemplaza la revisión humana. Una persona del equipo sabe que ese endpoint lo usa una app vieja, que ese cliente tiene un formato raro de fechas, que esa tabla no se toca los fines de mes. Nada de eso está en el código.
Que la documentación no se pudra
El verdadero enemigo de la documentación no es no escribirla, sino que quede desactualizada y mienta. Un documento viejo es peor que ninguno, porque alguien lo va a seguir.
Algunos hábitos que ayudan, con o sin modelo:
- Documentar cerca del código (docstrings, README del módulo) y no en un wiki aparte que nadie abre.
- Incluir en el checklist del pull request una pregunta: ¿cambia esto algo de lo documentado?
- Usar el modelo como detector: pasarle el diff junto con el texto existente y pedirle que señale qué frases quedaron desactualizadas.
- Preferir ejemplos que se puedan ejecutar, como doctests o fragmentos que corran en la integración continua, porque fallan cuando dejan de ser ciertos.
El tercer punto es de los usos más subestimados. Comparar dos textos y marcar contradicciones es una tarea que los modelos hacen bastante bien, y te ahorra releer todo el manual cada vez que tocás algo.
Si querés una regla simple para todo esto: dejá que el modelo escriba el primer borrador y la lista de sospechas, y que las decisiones y la última lectura sean tuyas. Lo que sale con tu nombre en el repositorio es tu responsabilidad, lo haya tipeado quien lo haya tipeado.