Escribe código como lo mantendrá una persona

Artículo original ↗ Discusión en Hacker News ↗

Comentarios, nomenclatura y legibilidad

  • Muchos prefieren comentarios mínimos y una nomenclatura clara por encima de comentarios abundantes.
  • Los comentarios redundantes de “explicar qué hace el código” se consideran ruido y probablemente se deterioren; los comentarios deben explicar el “por qué”, no el “qué” ni “cómo funciona el framework”.
  • Algunos defienden un flujo de trabajo parecido a la programación literaria (escribir primero la prosa/la intención y luego el código), pero reconocen que a menudo esto degenera en repetir el código.
  • El consenso: buenos nombres, estructura simple y comentarios ocasionales de “aquí hay dragones / esta es la razón” son lo ideal.

Comentarios y estilo generados por LLM

  • Fuerte frustración con los LLM produciendo comentarios verbosos y de poco valor, notas históricas y charla sobre el proceso de implementación.
  • Los modelos suelen describir fundamentos del lenguaje, rarezas del código circundante o el comportamiento de quien llama, rompiendo el encapsulamiento y quedando obsoletos rápidamente.
  • Los intentos de restringir esto mediante reglas en CLAUDE.md / AGENTS.md ayudan algo, pero se siguen de forma inconsistente; las instrucciones negativas (“no hagas X”) fallan especialmente.

Productividad vs mantenibilidad con IA

  • Algunos afirman un rendimiento de 10x en características/correcciones de errores al enviar lo que pase las pruebas y dejar que la IA “se encargue del desorden después”.
  • Otros advierten que este tipo de chapuza se acumula: lógica duplicada, reglas de negocio divergentes y capas defensivas anidadas hacen que el trabajo futuro de la IA y de las personas sea más lento y arriesgado.
  • Hay debate sobre si la velocidad a corto plazo se verá compensada por la complejidad a largo plazo, especialmente en bases de código grandes.

Prompts, listas de verificación y flujos de revisión

  • Muchos usan CLAUDE.md / AGENTS.md a nivel de proyecto junto con comandos explícitos “/review” con listas largas de verificación (DRY, estilo, duplicación, código muerto, pruebas, documentación).
  • Algunos dividen la revisión en varios pases especializados (seguridad, accesibilidad, rendimiento, simplificación) e incluso revisión adversaria con varios modelos.
  • Otros informan de rendimientos decrecientes a medida que crecen las listas de instrucciones; los modelos siguen ignorando reglas básicas (p. ej., uso de git), lo que requiere barandillas a nivel de sistema.

Herramientas tradicionales y barandillas

  • Analizadores estáticos, linters, formateadores de código, detectores de duplicación y comprobaciones pre-commit/CI se recomiendan ampliamente como líneas base no estocásticas.
  • Algunos escriben linters personalizados o comprobaciones a nivel de compilador para imponer cosas que los LLM violan habitualmente (sin números mágicos, sin imports dinámicos, requisitos de documentación/pruebas).

Roles de humanos frente a IA

  • Varios desarrolladores ahora usan los LLM principalmente para exploración, refactorización y revisión, pero siguen escribiendo a mano el código central.
  • Otros adoptan flujos de trabajo muy centrados en IA, aceptando que puede que las personas ya no mantengan un modelo mental completo del sistema y, en su lugar, confíen en andamiajes y herramientas robustas.
  • En el fondo, muchos enfatizan que la estructura mantenible, el DRY y las abstracciones claras siguen importando, tanto para personas como para agentes que consuman el código más adelante.