La documentacion debe explicar decisiones, no repetir sintaxis
Lo util es dejar claro que problema resuelve cada bloque, que dependencias tiene y que restricciones de negocio o integracion deben respetarse.
El contexto de origen importa mucho
Si una pieza nace de un prototipo, de una prueba o de una urgencia, eso debe quedar visible para decidir luego si conservarla, refactorizarla o aislarla.
Sin convenciones comunes el codigo se vuelve anonimo
Nombres, capas, contratos, comentarios orientativos y pruebas evitan que el equipo herede un conjunto de fragmentos sin relato tecnico.
Preguntas clave
Si hay tests no hace falta documentar
Los tests ayudan, pero no sustituyen el razonamiento de arquitectura ni el contexto de negocio.
La IA ya puede comentar el codigo sola
Puede ayudar, pero hay que revisar que los comentarios sean utiles y veraces.
Esto solo importa en proyectos grandes
Importa aun mas en equipos pequenos donde el conocimiento se concentra rapido.