Clang-Format

Configuration de clang-format

Configurez l'outil de formatage de code clang-format à l'aide de modèles prêts à l'emploi, de scripts d'intégration et d'une documentation de référence complète.

Objectif

Cette compétence fournit des flux de travail procéduraux pour les tâches de configuration de clang-format :

• Créer de nouveaux fichiers .clang-format à partir de modèles éprouvés
• Analyser le style de code existant et générer des configurations correspondantes
• Configurer l'intégration avec les éditeurs et Git à l'aide de scripts fournis
• Résoudre les problèmes de formatage en s'appuyant sur la documentation de référence

Routage des flux de travail par type de déclencheur

Une fois invoquée, acheminez vers le flux de travail approprié en fonction du déclencheur activé :

Déclencheur 1 : Mention explicite de clang-format → Si l'utilisateur demande des options spécifiques : Consultez les références dans references/01-09.md pour la catégorie concernée → Si l'utilisateur a besoin d'une référence complète : Dirigez-le vers references/complete/clang-format-style-options.md → Si l'utilisateur demande l'utilisation en ligne de commande : Référez-vous à references/cli-usage.md

Déclencheur 2 : Demande d'analyse de style de code → Suivez le flux de travail "Analyse du style de code existant" ci-dessous → Examinez systématiquement les échantillons de code (accolades → indentation → espaces → retours à la ligne → alignement) → Faites correspondre les motifs au modèle le plus proche dans assets/configs/ → Générez une hypothèse de configuration initiale sous forme de fichier temporaire "/tmp/<nom_depot>/hypothese_<numéro>.clang-format" → VÉRIFIEZ L'IMPACT : Exécutez clang-format --style="/tmp/<nom_depot>/hypothese_<numéro>.clang-format" fichier.cpp | diff - fichier.cpp sur 3 à 5 échantillons représentatifs → MESUREZ L'IMPACT à l'aide d'une notation pondérée : • Métrique 1 : Changements de nombre de lignes (lignes ajoutées/supprimées) - poids 10 • Métrique 2 : Changements d'espacement en ligne (espaces dans les lignes existantes) - poids 1 • Score d'impact = (changements_lignes × 10) + (changements_espaces × 1) • Un score plus bas = moins d'impact sur les conflits de rebasage, les futures analyses de git-diff et les revues de modifications des demandes de fusion = meilleure configuration → ITÉREZ : Ajustez les options de configuration en ciblant les réglages ayant le plus d'impact, retestez, comparez les scores → RÉPÉTEZ jusqu'à atteindre le score minimal possible tout en maintenant une application cohérente du style → RAPORTEZ À L'UTILISATEUR : Présentez la configuration gagnante avec : • Score d'impact final et détail (changements de lignes vs changements d'espaces) • Tableau comparatif de toutes les hypothèses testées et leurs scores • Exemples de diff montrant ce qui changera, avec des commandes permettant à l'utilisateur de tester lui-même sur ses fichiers • Justification de la configuration sélectionnée → ATTENDEZ L'APPROBATION DE L'UTILISATEUR avant de finaliser la configuration → Après approbation uniquement : fournissez le fichier de configuration final

Déclencheur 3 : Opérations sur les fichiers de configuration → Si création : Suivez le flux de travail "Création d'une nouvelle configuration à partir d'un modèle" → Si modification : Lisez la configuration actuelle, identifiez les modifications nécessaires, consultez le guide de catégorie concerné → Si génération à partir du code : Utilisez le flux de travail du déclencheur 2 (analyse de style de code)

Déclencheur 4 : Investigation d'un comportement de formatage → Suivez le flux de travail "Résolution des problèmes de formatage" ci-dessous → Vérifiez la détection de la configuration avec --dump-config → Identifiez la catégorie affectée, consultez le guide references/0X.md correspondant → Testez des options isolées avec une configuration minimale

Déclencheur 5 : Demandes sur les options de style → Faites correspondre la question à une catégorie : accolades → 03, indentation → 04, espacement → 05, alignement → 01, retours à la ligne → 02 → Référez-vous au guide de catégorie spécifique dans references/ → Fournissez des exemples tirés de quick-reference.md si applicable

Déclencheur 6 : Demandes de perturbation minimale → Utilisez le flux de travail "Analyse du style de code existant" pour faire correspondre les motifs actuels → Insistez sur le fait de partir du modèle le plus proche pour minimiser les changements → Testez sur des échantillons représentatifs avant l'application à l'ensemble du projet → Documentez les motifs qui ont été préservés par rapport à ceux qui ont été normalisés

Ressources fournies

Modèles de configuration (assets/configs/)

Sept modèles .clang-format prêts à l'emploi, optimisés pour des scénarios courants :

• google-cpp-modified.clang-format - Style Google C++ avec indentation de 4 espaces, limite de 120 colonnes
• linux-kernel.clang-format - Normes de codage du noyau Linux (tabs, accolades K&R)
• microsoft-visual-studio.clang-format - Conventions Microsoft/Visual Studio
• modern-cpp17-20.clang-format - Style moderne C++17/20 avec des idiomes contemporains
• compact-dense.clang-format - Style compact pour les environnements à espace restreint
• readable-spacious.clang-format - Style spacieux privilégiant la lisibilité
• multi-language.clang-format - Configuration multi-langages (C++, JavaScript, Java)

Quand utiliser les modèles : Démarrer de nouveaux projets, établir des normes d'équipe, ou tester rapidement des approches de formatage.

Scripts d'intégration (assets/integrations/)

Trois scripts d'intégration pour éditeurs et Git :

• pre-commit - Script de hook Git pour le formatage automatique des fichiers indexés (fonctionne avec les frameworks pre-commit ou prek)
• vimrc-clang-format.vim - Configuration Vim pour le formatage à la sauvegarde
• emacs-clang-format.el - Configuration Emacs pour l'intégration de clang-format

Quand utiliser les intégrations : Mettre en place un formatage automatique dans le flux de travail de développement.

Remarque : Le script de hook pre-commit fonctionne à la fois avec le framework pre-commit (Python) et prek (alternative Rust). Les deux frameworks utilisent .pre-commit-config.yaml avec une syntaxe identique.

Documentation de référence (references/)

Documentation détaillée organisée par catégorie :

Navigation rapide :

• index.md - Vue d'ensemble et hub de documentation
• quick-reference.md - Configurations complètes avec explications
• cli-usage.md - Utilisation en ligne de commande, configuration des éditeurs, intégration CI/CD

Catégories d'options (01-09.md) :

1. 01-alignment.md - Alignement vertical des déclarations, affectations, opérateurs
2. 02-breaking.md - Règles de saut de ligne et de retour à la ligne
3. 03-braces.md - Styles de placement des accolades (K&R, Allman, GNU, etc.)
4. 04-indentation.md - Règles d'indentation et cas particuliers
5. 05-spacing.md - Contrôle des espaces autour des opérateurs, mots-clés
6. 06-includes.md - Organisation et tri des inclusions/imports
7. 07-languages.md - Options spécifiques aux langages pour C++, Java, JavaScript
8. 08-comments.md - Formatage et réorganisation des commentaires
9. 09-advanced.md - Système de pénalités, formatage des chaînes brutes, fonctionnalités expérimentales

Référence complète (complete/) :

• clang-format-cli.md - Documentation complète de l'interface en ligne de commande
• clang-format-style-options.md - Les 194 options de style avec exemples

Flux de travail courants

Création d'une nouvelle configuration à partir d'un modèle

Pour créer un nouveau fichier .clang-format :

1. Identifiez les besoins (guide de style, préférences de l'équipe, langage)
2. Sélectionnez le modèle le plus proche dans assets/configs/
3. Copiez le modèle à la racine du projet sous le nom .clang-format
4. Testez le formatage : clang-format --dry-run fichier.cpp
5. Personnalisez les options spécifiques en utilisant references/01-09.md si nécessaire
6. Vérifiez les modifications : clang-format fichier.cpp | diff - fichier.cpp

Exemple :

# Copie du modèle Google C++
cp assets/configs/google-cpp-modified.clang-format /chemin/vers/projet/.clang-format

# Test sur un fichier exemple
clang-format --dry-run /chemin/vers/projet/src/main.cpp

# Appliquer si satisfait
clang-format -i /chemin/vers/projet/src/*.cpp

Analyse du style de code existant

Pour générer une configuration correspondant au code existant :

1. Examinez les échantillons de code pour les motifs de formatage
2. Identifiez les caractéristiques clés :
   • Placement des accolades → consultez references/03-braces.md
   • Indentation (espaces/tabs, largeur) → consultez references/04-indentation.md
   • Espacement (opérateurs, mots-clés) → consultez references/05-spacing.md
   • Sauts de ligne (limite de colonnes, retour à la ligne) → consultez references/02-breaking.md
   • Motifs d'alignement → consultez references/01-alignment.md
3. Faites correspondre les motifs au style de base le plus proche dans references/quick-reference.md
4. Commencez avec ce modèle provenant de assets/configs/
5. Surchargez les options spécifiques pour correspondre aux motifs observés
6. Testez sur des échantillons de code représentatifs
7. Itérez jusqu'à ce que le formatage corresponde au style existant

Ce flux de travail minimise les modifications d'espacement uniquement lors de l'introduction de clang-format dans des projets existants.

Configuration de l'intégration avec l'éditeur

Pour activer le formatage à la sauvegarde dans les éditeurs :

Vim :

1. Copiez le contenu de assets/integrations/vimrc-clang-format.vim dans .vimrc
2. Redémarrez Vim ou sourcez la configuration
3. Sauvegardez n'importe quel fichier C/C++/Java pour déclencher le formatage

Emacs :

1. Copiez assets/integrations/emacs-clang-format.el dans la configuration Emacs
2. Redémarrez Emacs ou évaluez la configuration
3. Sauvegardez n'importe quel fichier pris en charge pour déclencher le formatage

Autres éditeurs : Consultez references/cli-usage.md pour les instructions de configuration de VS Code, CLion et autres éditeurs.

Configuration du hook Git pour le formatage

Option 1 : Utilisation du framework pre-commit/prek (Recommandé) :

Configurez dans .pre-commit-config.yaml :

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

Puis installez : pre-commit install ou prek install

Option 2 : Hook Git manuel :

1. Copiez assets/integrations/pre-commit dans .git/hooks/pre-commit
2. Rendez-le exécutable : chmod +x .git/hooks/pre-commit
3. Testez en indexant et en commitant des modifications

Le hook formate uniquement les fichiers indexés, préservant les modifications non indexées.

Résolution des problèmes de formatage

Lorsque le formatage produit des résultats inattendus :

1. Vérifiez la détection de la configuration : clang-format --dump-config fichier.cpp
2. Consultez les options de commande dans references/cli-usage.md
3. Identifiez la catégorie de formatage affectée (accolades, espacement, sauts de ligne, etc.)
4. Consultez le guide de catégorie concerné dans references/01-09.md
5. Testez des options isolées : créez une configuration minimale avec l'option suspecte
6. Pour des détails complets sur les options, consultez references/complete/clang-format-style-options.md

Configuration des vérifications de formatage CI/CD

Pour appliquer le formatage dans l'intégration continue :

1. Consultez les exemples CI dans references/cli-usage.md
2. Ajoutez une vérification clang-format au pipeline :

   # Vérifier le formatage sans modifier les fichiers
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. Configurez pour échouer la build en cas de violation de formatage
4. Documentez les exigences de formatage pour les contributeurs

Concepts clés

Styles de base : Des configurations prédéfinies (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) fournissent des points de départ. Définissez avec BasedOnStyle: Google puis surchargez les options spécifiques.

Prise en charge multi-langages : Configurez différents langages séparément dans un seul fichier à l'aide de la clé Language:. Voir assets/configs/multi-language.clang-format pour un exemple.

Système de pénalités : clang-format utilise des pénalités pour choisir entre les alternatives de formatage. Des valeurs de pénalité plus élevées découragent des choix spécifiques. Voir references/09-advanced.md pour les détails.

Affinement progressif : Commencez avec le modèle le plus proche des exigences, puis personnalisez de manière incrémentielle. Testez fréquemment sur des échantillons de code représentatifs.

Test des configurations

# Aperçu des modifications sans modifier le fichier
clang-format --dry-run fichier.cpp

# Afficher le diff des modifications proposées
clang-format fichier.cpp | diff - fichier.cpp

# Appliquer le formatage au fichier
clang-format -i fichier.cpp

# Formater tout le projet
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Vérifier le formatage dans le CI (échec en cas de violation)
clang-format --dry-run --Werror src/**/*.{cpp,h}

Stratégie de navigation

Pour la plupart des tâches, suivez cette progression :

1. Commencez avec les modèles : Parcourez assets/configs/ pour des configurations prêtes à l'emploi
2. Référence rapide : Consultez references/quick-reference.md pour des configurations complètes avec explications
3. Guides par catégorie : Consultez references/01-09.md pour des catégories d'options spécifiques
4. Utilisation en ligne de commande : Référez-vous à references/cli-usage.md pour les détails de la ligne de commande et de l'intégration
5. Référence complète : Utilisez references/complete/ pour une documentation exhaustive des options

Lors de l'analyse de code ou du dépannage, identifiez l'aspect de formatage (accolades, espacement, alignement, etc.) et accédez directement au guide de catégorie correspondant dans references/.