clang-format 配置

Configuració de clang-format

Configureu l'eina de format de codi clang-format mitjançant plantilles ja preparades, scripts d'integració i documentació de referència completa.

Propòsit

Aquest skill proporciona fluxos de treball procedimentals per a tasques de configuració de clang-format:

• Crear nous fitxers .clang-format a partir de plantilles provades
• Analitzar l'estil de codi existent i generar configuracions coincidents
• Configurar la integració d'editor i git amb scripts inclosos
• Resoldre problemes de comportament de format utilitzant documentació de referència

Enrutament de flux de treball per tipus de desencadenant

Un cop invocat, enruteu al flux de treball adequat segons el desencadenant que s'hagi activat:

Desencadenant 1: Menció explícita de clang-format → Si l'usuari pregunta sobre opcions específiques: Consulteu references/01-09.md per a la categoria rellevant → Si l'usuari necessita una referència completa: Dirigiu-vos a references/complete/clang-format-style-options.md → Si l'usuari pregunta sobre l'ús de la CLI: Consulteu references/cli-usage.md

Desencadenant 2: Sol·licitud d'anàlisi d'estil de codi → Seguiu el flux de treball "Analitzant l'estil de codi existent" a continuació → Examineu les mostres de codi sistemàticament (claus → sagnat → espaiat → salts de línia → alineació) → Mapeu els patrons a la plantilla més propera a assets/configs/ → Genereu una hipòtesi de configuració inicial com a fitxer de configuració temporal "/tmp/<nom_repositori>/hypothesis_.clang-format" → VERIFIQUEU L'IMPACTE: Executeu clang-format --style="/tmp/<nom_repositori>/hypothesis_<nombre>.clang-format" fitxer.cpp | diff - fitxer.cpp en 3-5 mostres representatives → MESUREU L'IMPACTE mitjançant una puntuació ponderada: • Mètrica 1: Canvis en el nombre de línies (línies afegides/eliminades) - pes 10 • Mètrica 2: Canvis d'espais en blanc dins de la línia (espais dins de línies existents) - pes 1 • Puntuació d'impacte = (canvis_nombre_línies × 10) + (canvis_espais × 1) • Puntuació més baixa = menor impacte en conflictes de rebase, anàlisi futura de git-diff i revisions de canvis en sol·licituds de fusió = millor configuració → ITEREU: Ajusteu les opcions de configuració orientades a les configuracions d'alt impacte, torneu a provar, compareu puntuacions → REPETIU fins a assolir la puntuació mínima assolible mantenint un estil coherent → INFORMEU A L'USUARI: Presenteu la configuració guanyadora amb: • Puntuació d'impacte final i desglossament (canvis de línies vs canvis d'espais) • Taula comparativa que mostri totes les hipòtesis provades i les seves puntuacions • Exemples de fragments de diff que mostrin què canviarà, amb ordres perquè l'usuari ho provi ell mateix amb fitxers de la seva elecció. • Raonament per a la configuració seleccionada → ESPEREU L'APROVACIÓ DE L'USUARI abans de finalitzar la configuració → Només després de l'aprovació: proporcioneu el fitxer de configuració final

Desencadenant 3: Operacions amb fitxers de configuració → Si es crea un de nou: Seguiu el flux de treball "Creant una configuració nova a partir d'una plantilla" → Si es modifica un d'existent: Llegiu la configuració actual, identifiqueu els canvis necessaris, consulteu la guia de categoria rellevant → Si es genera a partir de codi: Utilitzeu el flux de treball del Desencadenant 2 (anàlisi d'estil de codi)

Desencadenant 4: Investigació de problemes de format → Seguiu el flux de treball "Resolent problemes de format" a continuació → Verifiqueu la detecció de configuració amb --dump-config → Identifiqueu la categoria afectada, consulteu la guia references/0X.md rellevant → Proveu opcions aïllades amb una configuració mínima

Desencadenant 5: Consultes sobre opcions d'estil → Mapeu la pregunta a una categoria: claus→03, sagnat→04, espaiat→05, alineació→01, salts de línia→02 → Consulteu la guia de categoria específica a references/ → Proporcioneu exemples de quick-reference.md si escau

Desencadenant 6: Sol·licituds de mínima alteració → Utilitzeu el flux de treball "Analitzant l'estil de codi existent" per coincidir amb els patrons actuals → Emfatitzeu començar des de la plantilla més propera per minimitzar els canvis → Proveu amb mostres representatives abans de l'aplicació a tot el projecte → Documenteu quins patrons s'han conservat vs normalitzat

Recursos inclosos

Plantilles de configuració (assets/configs/)

Set plantilles .clang-format preparades per utilitzar, optimitzades per a escenaris habituals:

• google-cpp-modified.clang-format - Estil Google C++ amb sagnat de 4 espais, límit de 120 columnes
• linux-kernel.clang-format - Estàndards de codi del kernel Linux (tabuladors, claus K&R)
• microsoft-visual-studio.clang-format - Convencions Microsoft/Visual Studio
• modern-cpp17-20.clang-format - Estil modern C++17/20 amb idioms contemporanis
• compact-dense.clang-format - Estil compacte per a entorns amb espai limitat
• readable-spacious.clang-format - Estil espaiós que prioritza la llegibilitat
• multi-language.clang-format - Configuració multiprocés (C++, JavaScript, Java)

Quan utilitzar plantilles: Inicieu projectes nous, establiu estàndards d'equip o proveu ràpidament enfocaments de format.

Scripts d'integració (assets/integrations/)

Tres scripts d'integració d'editor i git:

• pre-commit - Script de ganxo de Git per al format automàtic de fitxers preparats (funciona amb pre-commit o prek framework)
• vimrc-clang-format.vim - Configuració de Vim per formatar en desar
• emacs-clang-format.el - Configuració d'Emacs per a la integració de clang-format

Quan utilitzar integracions: Configureu el format automàtic al flux de treball de desenvolupament.

Nota: L'script de ganxo pre-commit funciona tant amb el framework pre-commit (Python) com amb prek (alternativa Rust). Ambdós frameworks utilitzen .pre-commit-config.yaml amb sintaxi idèntica.

Documentació de referència (references/)

Documentació detallada organitzada per categoria:

Navegació ràpida:

• index.md - Visió general i centre de documentació
• quick-reference.md - Configuracions completes de treball amb explicacions
• cli-usage.md - Ús de la línia d'ordres, configuració de l'editor, integració CI/CD

Categories d'opcions (01-09.md):

1. 01-alignment.md - Alineació vertical de declaracions, assignacions, operadors
2. 02-breaking.md - Regles de salts de línia i embolcall
3. 03-braces.md - Estils de col·locació de claus (K&R, Allman, GNU, etc.)
4. 04-indentation.md - Regles de sagnat i casos especials
5. 05-spacing.md - Control d'espais en blanc al voltant d'operadors, paraules clau
6. 06-includes.md - Organització i ordenació d'inclusions/importacions
7. 07-languages.md - Opcions específiques per a C++, Java, JavaScript
8. 08-comments.md - Format i refluix de comentaris
9. 09-advanced.md - Sistema de penalitzacions, format de cadenes literals, funcions experimentals

Referència completa (complete/):

• clang-format-cli.md - Documentació completa de la interfície de línia d'ordres
• clang-format-style-options.md - Totes les 194 opcions d'estil amb exemples

Fluxos de treball habituals

Creant una configuració nova a partir d'una plantilla

Per crear un fitxer .clang-format nou:

1. Identifiqueu els requisits (guia d'estil, preferències de l'equip, llenguatge)
2. Seleccioneu la plantilla més propera de assets/configs/
3. Copieu la plantilla a l'arrel del projecte com a .clang-format
4. Proveu el format: clang-format --dry-run fitxer.cpp
5. Personalitzeu opcions específiques utlitzant references/01-09.md segons sigui necessari
6. Verifiqueu els canvis: clang-format fitxer.cpp | diff - fitxer.cpp

Exemple:

# Copieu la plantilla Google C++
cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format

# Proveu amb un fitxer de mostra
clang-format --dry-run /path/to/project/src/main.cpp

# Apliqueu si esteu satisfet
clang-format -i /path/to/project/src/*.cpp

Analitzant l'estil de codi existent

Per generar una configuració que coincideixi amb el codi existent:

1. Examineu les mostres de codi per detectar patrons de format
2. Identifiqueu les característiques clau:
   • Col·locació de claus → consulteu references/03-braces.md
   • Sagnat (espais/tabuladors, amplada) → consulteu references/04-indentation.md
   • Espaiat (operadors, paraules clau) → consulteu references/05-spacing.md
   • Salts de línia (límit de columnes, embolcall) → consulteu references/02-breaking.md
   • Patrons d'alineació → consulteu references/01-alignment.md
3. Mapeu els patrons a l'estil base més proper a references/quick-reference.md
4. Comenceu amb aquesta plantilla de assets/configs/
5. Sobreescriviu opcions específiques per coincidir amb els patrons observats
6. Proveu amb mostres de codi representatives
7. Itereu fins que el format coincideixi amb l'estil existent

Aquest flux de treball minimitza els canvis només d'espais en blanc en introduir clang-format a projectes existents.

Configurant la integració d'editor

Per habilitar el format en desar als editors:

Vim:

1. Copieu el contingut de assets/integrations/vimrc-clang-format.vim a .vimrc
2. Reinicieu Vim o source la configuració
3. Deseu qualsevol fitxer C/C++/Java per activar el format

Emacs:

1. Copieu assets/integrations/emacs-clang-format.el a la configuració d'Emacs
2. Reinicieu Emacs o avalueu la configuració
3. Deseu qualsevol fitxer suportat per activar el format

Altres editors: Consulteu references/cli-usage.md per a instruccions de configuració de VS Code, CLion i altres editors.

Configurant un ganxo de Git per al format

Opció 1: Utilitzant el framework pre-commit/prek (Recomanat):

Configureu a .pre-commit-config.yaml:

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

Després instal·leu: pre-commit install o prek install

Opció 2: Ganxo de Git manual:

1. Copieu assets/integrations/pre-commit a .git/hooks/pre-commit
2. Feu-lo executable: chmod +x .git/hooks/pre-commit
3. Proveu-lo preparant i confirmant canvis

El ganxo només formata els fitxers preparats, conservant els canvis no preparats.

Resolent problemes de format

Quan el format produeix resultats inesperats:

1. Verifiqueu la detecció de configuració: clang-format --dump-config fitxer.cpp
2. Comproveu les opcions d'ordres a references/cli-usage.md
3. Identifiqueu la categoria de format afectada (claus, espaiat, salts de línia, etc.)
4. Consulteu la guia de categoria rellevant a references/01-09.md
5. Proveu opcions aïllades: creeu una configuració mínima amb l'opció sospitosa
6. Per a detalls complets d'opcions, consulteu references/complete/clang-format-style-options.md

Configurant verificacions de format CI/CD

Per imposar el format a la integració contínua:

1. Reviseu els exemples de CI a references/cli-usage.md
2. Afegiu una verificació de clang-format al pipeline:

   # Verifiqueu el format sense modificar fitxers
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. Configureu perquè la compilació falli en cas de violacions de format
4. Documenteu els requisits de format per als col·laboradors

Conceptes clau

Estils base: Configuracions predefinides (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) proporcionen punts de partida. Establiu BasedOnStyle: Google i després sobreescriviu opcions específiques.

Suport multiprocés: Configureu diferents llenguatges per separat en un sol fitxer mitjançant la clau Language:. Vegeu assets/configs/multi-language.clang-format per a un exemple.

Sistema de penalitzacions: clang-format utilitza penalitzacions per triar entre alternatives de format. Valors de penalització més alts desanimen opcions específiques. Vegeu references/09-advanced.md per a més detalls.

Refinament progressiu: Comenceu amb la plantilla més propera als requisits, després personalitzeu incrementalment. Proveu freqüentment amb mostres de codi representatives.

Provant configuracions

# Previsualitzeu els canvis sense modificar el fitxer
clang-format --dry-run fitxer.cpp

# Mostreu el diff dels canvis proposats
clang-format fitxer.cpp | diff - fitxer.cpp

# Apliqueu el format al fitxer
clang-format -i fitxer.cpp

# Formateu tot el projecte
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Verifiqueu el format a CI (falla en cas de violacions)
clang-format --dry-run --Werror src/**/*.{cpp,h}

Estratègia de navegació

Per a la majoria de tasques, seguiu aquesta progressió:

1. Començar amb plantilles: Navegueu per assets/configs/ per a configuracions ja preparades
2. Referència ràpida: Consulteu references/quick-reference.md per a configuracions completes amb explicacions
3. Guies de categoria: Consulteu references/01-09.md per a categories d'opcions específiques
4. Ús de la CLI: Consulteu references/cli-usage.md per a detalls de línia d'ordres i integració
5. Referència completa: Utilitzeu references/complete/ per a documentació exhaustiva d'opcions

Quan analitzeu codi o resoleu problemes, identifiqueu l'aspecte de format (claus, espaiat, alineació, etc.) i aneu directament a la guia de categoria rellevant a references/.