Normas de código limpio para la generación de código IA

Estas reglas guían la generación de código para producir un código de calidad profesional que pueda mantenerse.

Nombres significativos

Use nombres de intención reveladoras que expliquen por qué existe algo
Evitar la desinformación y las distinciones sin sentido (por ejemplo, data, info, manager)
Usar nombres pronunciables y de búsqueda
Nombres de clase: sustantivos (por ejemplo, UserAccount, PaymentProcessor)
Nombres del método: verbos (por ejemplo, calculateTotal, sendEmail)
Evite el mapeo mental y las codificaciones (notación húngara, prefijos)

Funciones

Mantener funciones pequeñas (< 20 líneas ideales)
Hacer una sola cosa - Principio de Responsabilidad Única
Un nivel de abstracción por función
Argumentos límite: 0-2 ideal, 3 máximo, evitar argumentos de bandera
Ningún efecto secundario - función debe hacer lo que su nombre dice
Separar los comandos (cambiar estado) de las consultas (return info)
Preferir excepciones sobre códigos de error

Observaciones

El código debe ser autoexplicativo - evitar comentarios cuando sea posible
Buenos comentarios: información legal, advertencias, TODOs, documentación pública de API
Comentarios erróneos: redundante, engañoso o explicativo de código incorrecto
Nunca comentar código - eliminarlo (control de versión preserva el historial)
Si necesita un comentario, considere refactorizar el código en su lugar

Formato

Mantenga los archivos pequeños y enfocados
Formateo vertical: conceptos relacionados de cerca, líneas en blanco conceptos separados
Formato horizontal: longitud de línea límite (80-120 caracteres)
Usar un estilo de sangría y equipo consistentes
Funciones relacionadas con el grupo

Objetos y estructuras de datos

Objetos: ocultar datos detrás de abstracciones, exponer el comportamiento a través de métodos
Estructuras de datos: exponer datos, tener un comportamiento mínimo
Ley de Demeter: sólo hablar con amigos inmediatos, evitar a.getB().getC().doSomething()
No expongas la estructura interna a través de getters/setters ciegamente

Manejo de errores

Usar excepciones, no devolver códigos o banderas de error
Escribir try-catch-finally primero cuando el código puede fallar
Proporcionar contexto en los mensajes de excepción
No regreses. null - devolver colecciones vacías o utilizar Opcional/Tal vez
No pases null como argumentos

Clases

Clases pequeñas: medidas por responsabilidades, no por líneas
Principio de responsabilidad única: una razón para cambiar
Alta cohesión: variables de clase utilizadas por muchos métodos
Acoplamiento bajo: dependencias mínimas entre clases
Principio abierto/cerrado: abierto para extensión, cerrado para modificación

Ensayos unitarios

Rápido, independiente, repetible, autovalidable, oportuno (F.I.R.S.T.)
Uno afirma por prueba (o un concepto)
Calidad del código de prueba igual a calidad del código de producción
Nombres de prueba legibles que describen lo que se está probando
Arreglar el patrón de los instrumentos de evaluación

Principios de calidad del código

SECAS (No repitas tu mismo): No hay duplicación
YAGNI (No vas a necesitarlo): No construir para futuros hipotéticos
KISS (Sencillo): Evitar la complejidad innecesaria
Regla de los Boy Scout: Deja código más limpio de lo que lo encontraste

Código huele a evitar

Funciones o clases largas
Código duplicado
Código muerto (variables no utilizadas, funciones, parámetros)
Envidia de las características (método más interesado en otra clase)
Inadecuada intimidad (clases que saben demasiado el uno del otro)
Listas de parámetros largos
Obsesión primitiva (sobreutilización de primitivos en lugar de objetos pequeños)
Interruptores/declaraciones de casos (considerar el polimorfismo)
Campos temporales (variables de clase utilizadas sólo a veces)

Condicional

Mantener el código concurrente separado de otro código
Limitar el alcance de los datos sincronizados/bloqueados
Usar colecciones seguras de roscas
Mantener secciones sincronizadas pequeñas
Conozca sus modelos de ejecución y primitivos

Diseño del sistema

Construcción separada del uso (inyección por dependencia)
Utilice fábricas, constructores para la creación de objetos complejos
Programa a interfaces, no implementaciones
Favorece la composición sobre la herencia
Aplicar patrones de diseño cuando se simplifican, no para mostrar

Refactorización

Refactorizar continuamente, no en lotes grandes
Siempre se someten a exámenes antes y después
Pequeños pasos: un cambio a la vez
Refactorizaciones comunes: Método de extracción, cambio de nombre, movimiento, en línea

Documentación

Código de autodocumentación > comentarios > documentos externos
Las API públicas necesitan documentación clara
Incluir ejemplos en la documentación
Mantenga los documentos cerca del código (idealmente en código)

Filosofía básica: Código se lee 10 veces más que escrito. Optimizar para la legibilidad y mantenimiento, no la astucia.

Última actualización: 4 de agosto de 2026 Versión de Claude Code: 2.1.220 Fuentes: - https://code.claude.com/docs/en/overview Modelos compatibles: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5