clang-format

Configuración de clang-format

Configura la herramienta de formateo de código clang-format usando plantillas listas para usar, scripts de integración y documentación de referencia completa.

Propósito

Esta habilidad proporciona flujos de trabajo procedimentales para tareas de configuración de clang-format:

• Crear nuevos archivos .clang-format a partir de plantillas probadas
• Analizar el estilo de código existente y generar configuraciones coincidentes
• Configurar la integración con editores y git usando scripts incluidos
• Solucionar problemas de comportamiento de formateo usando la documentación de referencia

Enrutamiento de flujo de trabajo por tipo de desencadenante

Una vez invocado, enruta al flujo de trabajo apropiado según qué desencadenante se haya activado:

Desencadenante 1: Mención explícita de clang-format → Si el usuario pregunta sobre opciones específicas: Consulta las referencias/01-09.md para la categoría relevante → Si el usuario necesita una referencia completa: Dirige a references/complete/clang-format-style-options.md → Si el usuario pregunta sobre el uso de la CLI: Referencia references/cli-usage.md

Desencadenante 2: Solicitud de análisis de estilo de código → Sigue el flujo de trabajo "Analizando el estilo de código existente" a continuación → Examina las muestras de código sistemáticamente (llaves→sangría→espaciado→saltos de línea→alineación) → Asigna los patrones a la plantilla más cercana en assets/configs/ → Genera una hipótesis de configuración inicial como un archivo de configuración temporal "/tmp/<nombre_repositorio>/hipótesis_<número>.clang-format" → VERIFICA EL IMPACTO: Ejecuta clang-format --style="/tmp/<nombre_repositorio>/hipótesis_<número>.clang-format" archivo.cpp | diff - archivo.cpp en 3-5 muestras representativas → MIDE EL IMPACTO usando puntuación ponderada: • Métrica 1: Cambios en el número de líneas (líneas añadidas/eliminadas) - peso 10 • Métrica 2: Cambios de espacios en blanco en línea (espaciado dentro de líneas existentes) - peso 1 • Puntuación de impacto = (cambios_en_número_de_líneas × 10) + (cambios_de_espacios_en_blanco × 1) • Una puntuación más baja = menor impacto en conflictos de rebase, análisis futuro de git-diff y revisiones de cambios en merge requests = mejor configuración → ITERA: Ajusta las opciones de configuración apuntando a las configuraciones de mayor impacto, vuelve a probar, compara puntuaciones → REPITE hasta alcanzar la puntuación mínima alcanzable mientras se mantiene una aplicación de estilo consistente → INFORMA AL USUARIO: Presenta la configuración ganadora con: • Puntuación de impacto final y desglose (cambios de línea vs cambios de espacios en blanco) • Tabla comparativa que muestre todas las hipótesis probadas y sus puntuaciones • Fragmentos de diff de ejemplo que muestren lo que cambiará, con comandos para que el usuario lo pruebe por sí mismo con los archivos que elija. • Justificación de la configuración seleccionada → ESPERA LA APROBACIÓN DEL USUARIO antes de finalizar la configuración → Solo después de la aprobación: proporciona el archivo de configuración final

Desencadenante 3: Operaciones con archivos de configuración → Si se crea uno nuevo: Sigue el flujo de trabajo "Creando una nueva configuración a partir de una plantilla" → Si se modifica uno existente: Lee la configuración actual, identifica los cambios necesarios, consulta la guía de categoría relevante → Si se genera a partir de código: Usa el flujo de trabajo del Desencadenante 2 (análisis de estilo de código)

Desencadenante 4: Investigación de comportamiento de formateo → Sigue el flujo de trabajo "Solucionando problemas de formato" a continuación → Verifica la detección de configuración con --dump-config → Identifica la categoría afectada, consulta la guía references/0X.md relevante → Prueba opciones aisladas con una configuración mínima

Desencadenante 5: Consultas sobre opciones de estilo → Asigna la pregunta a una categoría: llaves→03, sangría→04, espaciado→05, alineación→01, saltos de línea→02 → Consulta la guía de categoría específica en references/ → Proporciona ejemplos de quick-reference.md si corresponde

Desencadenante 6: Solicitudes de mínima disrupción → Usa el flujo de trabajo "Analizando el estilo de código existente" para coincidir con los patrones actuales → Enfatiza comenzar desde la plantilla más cercana para minimizar cambios → Prueba en muestras representativas antes de la aplicación en todo el proyecto → Documenta qué patrones se conservaron frente a los que se normalizaron

Recursos incluidos

Plantillas de configuración (assets/configs/)

Siete plantillas .clang-format listas para usar, optimizadas para escenarios comunes:

• google-cpp-modified.clang-format - Estilo Google C++ con sangría de 4 espacios, límite de 120 columnas
• linux-kernel.clang-format - Estándares de codificación del kernel de Linux (tabulaciones, llaves K&R)
• microsoft-visual-studio.clang-format - Convenciones de Microsoft/Visual Studio
• modern-cpp17-20.clang-format - Estilo moderno C++17/20 con modismos contemporáneos
• compact-dense.clang-format - Estilo compacto para entornos con limitaciones de espacio
• readable-spacious.clang-format - Estilo espacioso que prioriza la legibilidad
• multi-language.clang-format - Configuración multilingüe (C++, JavaScript, Java)

Cuándo usar plantillas: Iniciar nuevos proyectos, establecer estándares de equipo, o probar rápidamente enfoques de formateo.

Scripts de integración (assets/integrations/)

Tres scripts de integración para editores y git:

• pre-commit - Script de enganche de git para formateo automático de archivos preparados (funciona con el framework pre-commit o prek)
• vimrc-clang-format.vim - Configuración de Vim para formato al guardar
• emacs-clang-format.el - Configuración de Emacs para integración con clang-format

Cuándo usar integraciones: Configurar el formateo automático en el flujo de trabajo de desarrollo.

Nota: El script de enganche pre-commit funciona tanto con el framework pre-commit (Python) como con prek (alternativa en Rust). Ambos frameworks usan .pre-commit-config.yaml con sintaxis idéntica.

Documentación de referencia (references/)

Documentación detallada organizada por categoría:

Navegación rápida:

• index.md - Resumen y centro de documentación
• quick-reference.md - Configuraciones funcionales completas con explicaciones
• cli-usage.md - Uso desde línea de comandos, configuración de editores, integración CI/CD

Categorías de opciones (01-09.md):

1. 01-alignment.md - Alineación vertical de declaraciones, asignaciones, operadores
2. 02-breaking.md - Reglas de salto de línea y ajuste
3. 03-braces.md - Estilos de colocación de llaves (K&R, Allman, GNU, etc.)
4. 04-indentation.md - Reglas de sangría y casos especiales
5. 05-spacing.md - Control de espacios en blanco alrededor de operadores, palabras clave
6. 06-includes.md - Organización y ordenación de includes/imports
7. 07-languages.md - Opciones específicas de lenguaje para C++, Java, JavaScript
8. 08-comments.md - Formato de comentarios y reflujo
9. 09-advanced.md - Sistema de penalización, formateo de cadenas sin procesar, características experimentales

Referencia completa (complete/):

• clang-format-cli.md - Documentación completa de la interfaz de línea de comandos
• clang-format-style-options.md - Las 194 opciones de estilo con ejemplos

Flujos de trabajo comunes

Creando una nueva configuración a partir de una plantilla

Para crear un nuevo archivo .clang-format:

1. Identifica los requisitos (guía de estilo, preferencias del equipo, lenguaje)
2. Selecciona la plantilla más cercana de assets/configs/
3. Copia la plantilla a la raíz del proyecto como .clang-format
4. Prueba el formato: clang-format --dry-run archivo.cpp
5. Personaliza opciones específicas usando referencias/01-09.md según sea necesario
6. Verifica los cambios: clang-format archivo.cpp | diff - archivo.cpp

Ejemplo:

# Copiar plantilla Google C++
cp assets/configs/google-cpp-modified.clang-format /ruta/al/proyecto/.clang-format

# Probar en un archivo de muestra
clang-format --dry-run /ruta/al/proyecto/src/main.cpp

# Aplicar si está satisfecho
clang-format -i /ruta/al/proyecto/src/*.cpp

Analizando el estilo de código existente

Para generar una configuración que coincida con el código existente:

1. Examina las muestras de código en busca de patrones de formato
2. Identifica las características clave:
   • Colocación de llaves → consulta references/03-braces.md
   • Sangría (espacios/tabulaciones, ancho) → consulta references/04-indentation.md
   • Espaciado (operadores, palabras clave) → consulta references/05-spacing.md
   • Saltos de línea (límite de columna, ajuste) → consulta references/02-breaking.md
   • Patrones de alineación → consulta references/01-alignment.md
3. Asigna los patrones al estilo base más cercano en references/quick-reference.md
4. Comienza con esa plantilla de assets/configs/
5. Sobrescribe opciones específicas para que coincidan con los patrones observados
6. Prueba en muestras de código representativas
7. Itera hasta que el formato coincida con el estilo existente

Este flujo de trabajo minimiza los cambios solo de espacios en blanco al introducir clang-format en proyectos existentes.

Configurando la integración con el editor

Para habilitar el formato al guardar en editores:

Vim:

1. Copia el contenido de assets/integrations/vimrc-clang-format.vim a .vimrc
2. Reinicia Vim o recarga la configuración
3. Guarda cualquier archivo C/C++/Java para activar el formato

Emacs:

1. Copia assets/integrations/emacs-clang-format.el a la configuración de Emacs
2. Reinicia Emacs o evalúa la configuración
3. Guarda cualquier archivo compatible para activar el formato

Otros editores: Consulta references/cli-usage.md para instrucciones de configuración de VS Code, CLion y otros editores.

Configurando el enganche de git para formateo

Opción 1: Usando el framework pre-commit/prek (Recomendado)

Configura en .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v19.1.7
    hooks:
      - id: clang-format

Luego instala: pre-commit install o prek install

Opción 2: Enganche de git manual

1. Copia assets/integrations/pre-commit a .git/hooks/pre-commit
2. Hazlo ejecutable: chmod +x .git/hooks/pre-commit
3. Prueba preparando y confirmando cambios

El enganche solo formatea los archivos preparados, preservando los cambios no preparados.

Solucionando problemas de formato

Cuando el formato produce resultados inesperados:

1. Verifica la detección de configuración: clang-format --dump-config archivo.cpp
2. Revisa las opciones de comando en references/cli-usage.md
3. Identifica la categoría de formato afectada (llaves, espaciado, saltos de línea, etc.)
4. Consulta la guía de categoría relevante en references/01-09.md
5. Prueba opciones aisladas: crea una configuración mínima con la opción sospechosa
6. Para detalles completos de opciones, consulta references/complete/clang-format-style-options.md

Configurando comprobaciones de formato en CI/CD

Para imponer el formato en la integración continua:

1. Revisa los ejemplos de CI en references/cli-usage.md
2. Añade una comprobación de clang-format al pipeline:

   # Comprobar formato sin modificar archivos
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. Configura para que falle la compilación en caso de violaciones de formato
4. Documenta los requisitos de formato para los contribuyentes

Conceptos clave

Estilos base: Las configuraciones predefinidas (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) proporcionan puntos de partida. Establece con BasedOnStyle: Google y luego sobrescribe opciones específicas.

Soporte multilingüe: Configura diferentes lenguajes por separado en un solo archivo usando la clave Language:. Consulta assets/configs/multi-language.clang-format para ver un ejemplo.

Sistema de penalización: clang-format usa penalizaciones para elegir entre alternativas de formato. Los valores de penalización más altos desalientan elecciones específicas. Consulta references/09-advanced.md para obtener más detalles.

Refinamiento progresivo: Comienza con la plantilla más cercana a los requisitos, luego personaliza incrementalmente. Prueba con frecuencia en muestras de código representativas.

Probando configuraciones

# Vista previa de cambios sin modificar el archivo
clang-format --dry-run archivo.cpp

# Muestra el diff de los cambios propuestos
clang-format archivo.cpp | diff - archivo.cpp

# Aplica formato al archivo
clang-format -i archivo.cpp

# Formatea todo el proyecto
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Comprueba formato en CI (falla en violaciones)
clang-format --dry-run --Werror src/**/*.{cpp,h}

Estrategia de navegación

Para la mayoría de las tareas, sigue esta progresión:

1. Comienza con plantillas: Explora assets/configs/ en busca de configuraciones listas para usar
2. Referencia rápida: Consulta references/quick-reference.md para configuraciones completas con explicaciones
3. Guías de categoría: Consulta references/01-09.md para categorías de opciones específicas
4. Uso de la CLI: Referencia references/cli-usage.md para detalles de línea de comandos e integración
5. Referencia completa: Usa references/complete/ para documentación exhaustiva de opciones

Al analizar código o solucionar problemas, identifica el aspecto del formato (llaves, espaciado, alineación, etc.) y salta directamente a la guía de categoría relevante en references/.