Définissez des styles de codage cohérents avec EditorConfig

  • Article

Pour imposer des styles de codage cohérents à toutes les personnes travaillant dans une base de code, vous pouvez ajouter un fichier .editorConfig à votre solution ou à votre projet. Les paramètres des fichiers EditorConfig sont conformes à une spécification de format de fichier maintenue par EditorConfig.org. De nombreux éditeurs de code et applications prennent en charge les fichiers EditorConfig, y compris Visual Studio. Comme les paramètres se trouvent dans un fichier, ils accompagnent votre code et peuvent être utilisés même en dehors de Visual Studio.

Dans Visual Studio, les paramètres du fichier EditorConfig ont la priorité sur les divers paramètres globaux de l'éditeur de texte disponibles sous Outils>Options>Éditeur de texte>C/C++>Style de code. Vous pouvez utiliser un fichier EditorConfig pour adapter chaque base de code afin d'utiliser les paramètres de l'éditeur de texte spécifiques à ce projet.

Vous pouvez remplir manuellement un fichier EditorConfig ou le générer automatiquement en fonction des paramètres de style de code que vous avez choisis dans Visual Studio. Pour créer un nouveau fichier .editorconfig en fonction de vos paramètres Visual Studio actuels, dans le menu principal de Visual Studio, choisissez Outils>Options>Éditeur de texte>C/C++>Général. Choisissez ensuite Générer un fichier .editorconfig à partir des paramètres. Choisissez le dossier dans lequel se trouve votre projet, puis sélectionnez Sélectionner un dossier pour enregistrer le fichier .editorconfig.

Lorsque vous utilisez un fichier EditorConfig, vous pouvez continuer à définir vos préférences d'éditeur personnelles dans l'éditeur de texte de Visual Studio. Ces paramètres de l’éditeur de texte s’appliquent chaque fois que vous travaillez dans une base de code sans fichier EditorConfig, ou lorsque le fichier EditorConfig ne remplace pas un paramètre particulier. Un exemple d’une telle préférence est de savoir si utiliser des tabulations ou des espaces pour le style d’indentation du code.

Lorsque vous ajoutez un fichier EditorConfig à votre projet dans Visual Studio, seules les nouvelles lignes de code sont formatées en fonction des paramètres de l’EditorConfig. La mise en forme du code existant ne change pas, à moins que vous exécutiez l’une des commandes suivantes :

  • Nettoyage du code.

    Sélectionnez Nettoyage de code dans l’éditeur Visual Studio, ou appuyez sur Ctrl+K, Ctrl+E>. Cette commande s’applique aux paramètres d’espacement, tels que le style d’indentation, et aux paramètres de style de code sélectionnés, tels que les préférences de parenthèses.

  • Mettre le document en forme.

    Sélectionnez Modifier>Avancé>Mettre le document en forme, ou appuyez sur Ctrl+K, Ctrl+D dans le profil par défaut. Cette commande s’applique uniquement aux paramètres d’espacement, tels que le style d’indentation.

Cohérence du code

Les paramètres du fichier EditorConfig vous permettent de maintenir des styles de codage et des conventions cohérents dans une base de code, quel que soit l’éditeur ou l’IDE que vous utilisez. Certains styles de codage que vous pouvez contrôler sont le style d’indentation, la largeur de tabulation, les caractères de fin de ligne et l’encodage. Par exemple, si votre base de code C# a pour convention que les indentations utilisent cinq caractères d’espace, que les documents utilisent l’encodage UTF-8 et que les lignes se terminent par CR/LF, vous pouvez configurer un fichier EditorConfig pour utiliser cette convention.

Les fichiers EditorConfig sont utiles lorsque les conventions de codage que vous utilisez sur vos projets personnels diffèrent de celles utilisées sur les projets de votre équipe. Par exemple, vous préférez qu’une indentation ajoute un caractère de tabulation dans votre code. Cependant, votre équipe peut préférer qu’une indentation ajoute plutôt quatre espaces. Les fichiers EditorConfig apportent une réponse à ce problème en offrant la possibilité de disposer d’une configuration pour chaque scénario.

Étant donné qu'un fichier .editorconfig de la base de code contient les paramètres EditorConfig, ces derniers voyagent avec la base de code. Tant que vous ouvrez le fichier de code dans un éditeur compatible avec EditorConfig, les paramètres de l’éditeur de texte sont activés.

Remarque

Les conventions que vous définissez dans un fichier EditorConfig ne peuvent pas être imposées dans un pipeline CI/CD en tant qu’erreurs ou avertissements de génération. Les écarts de style apparaissent seulement dans l’éditeur Visual Studio et dans la Liste d’erreurs.

Paramètres pris en charge

L’éditeur de Visual Studio prend en charge l’ensemble principal des propriétés d’EditorConfig :

  • indent_style
  • indent_size
  • tab_width
  • end_of_line
  • charset
  • trim_trailing_whitespace
  • insert_final_newline
  • root

EditorConfig prend en charge tous les langages pris en charge par Visual Studio, sauf le support XML des paramètres de l’éditeur EditorConfig.

EditorConfig prend en charge les conventions de style de code, comme les conventions de langage, de formatage et de nomenclature pour C# et Visual Basic.

Ajout et suppression de fichiers EditorConfig

Lorsque vous ajoutez un fichier EditorConfig à votre projet ou base de code, Visual Studio formate toute nouvelle ligne de code que vous écrivez en fonction des paramètres du fichier EditorConfig. Cependant, Visual Studio ne convertit pas automatiquement les styles existants en nouveaux styles tant que vous ne formatez pas le document ou ne lancez pas le Nettoyage du code. Par exemple, si les indentations de votre fichier sont formatées avec des tabulations et que vous ajoutez un fichier EditorConfig qui formate les indentations avec des espaces, les caractères d’indentation ne sont pas automatiquement convertis en espaces. Lorsque vous formatez le document (sélectionnez Modifier>Avancé>Format du document ou appuyez sur Ctrl+K, Ctrl+D), les paramètres d’espacement du fichier EditorConfig sont appliqués aux lignes de code existantes.

Si vous supprimez un fichier EditorConfig de votre projet ou base de code, vous devez fermer et rouvrir tous les fichiers de code ouverts pour que les nouveaux paramètres globaux de l’éditeur prennent effet.

Ajouter un fichier EditorConfig à un projet

Pour ajouter un fichier EditorConfig à votre projet ou solution, suivez ces étapes :

  1. Ouvrez un projet ou une solution dans Visual Studio. Sélectionnez le nœud de solution ou de projet, selon que vos paramètres EditorConfig doivent s’appliquer à tous les projets de la solution ou à un seul. Vous pouvez également sélectionner un dossier dans votre projet ou votre solution pour y ajouter le fichier .editorconfig.

  2. Dans le menu, choisissez Projet>Ajouter un nouvel élément, ou appuyez sur Ctrl+Maj+A.

    La boîte de dialogue Ajouter un nouvel élément s’ouvre.

  3. Dans la zone de recherche, saisissez editorconfig.

    Deux modèles d'élément de Fichier editorconfig s’affichent dans les résultats de recherche.

    Capture d'écran montrant des modèles d'élément de fichier EditorConfig dans Visual Studio.

  4. Sélectionnez le modèle Fichier editorconfig (vide) pour ajouter un fichier EditorConfig prérempli avec des options EditorConfig par défaut pour l’espacement, le style de code et les conventions de nommage. Ou, sélectionnez le modèle Fichier editorconfig (.NET) pour ajouter un fichier EditorConfig prérempli avec les conventions .NET d’espacement, de style de code et de nommage par défaut.

    Un nouveau fichier .editorconfig apparaît dans l'Explorateur de solutions et s'ouvre dans l'éditeur sous la forme d'un nouvel onglet.

    Capture d'écran montrant le fichier .editorconfig dans l'Explorateur de solutions et l'éditeur.

  5. Éditez éventuellement le fichier, puis enregistrez-le.

Autres façons d’ajouter un fichier EditorConfig

Il existe d’autres façons d’ajouter un fichier EditorConfig au projet :

Priorité et hiérarchie des fichiers

Lorsque vous ajoutez un fichier .editorconfig à un dossier dans votre hiérarchie de fichiers, ses paramètres s'appliquent à tous les fichiers applicables à ce niveau et aux niveaux inférieurs. Vous pouvez également remplacer les paramètres EditorConfig d’un projet particulier, d’un code base ou d’une partie de code base qui utilise des conventions différentes de celles des autres parties du code base. Cela peut être utile lorsque vous incorporez du code en provenance d’ailleurs et que vous ne souhaitez pas changer ses conventions.

Procédez comme suit :

  • Pour remplacer tout ou partie des paramètres de EditorConfig, ajoutez un fichier .editorconfig au niveau de la hiérarchie des fichiers auquel vous souhaitez que ces paramètres remplacés s'appliquent. Les nouveaux paramètres du fichier EditorConfig s’appliquent aux fichiers du même niveau et aux fichiers dans les sous-répertoires.

    Capture d'écran montrant la hiérarchie d'EditorConfig.

  • Si vous souhaitez remplacer certains paramètres, mais pas tous, spécifiez uniquement ces paramètres dans le fichier .editorconfig. Seules les propriétés que vous avez explicitement énumérées dans le fichier .editorconfig de niveau inférieur sont remplacées. Les autres paramètres des fichiers de niveau supérieur .editorconfig continuent de s'appliquer.

  • Si vous voulez vous assurer qu'aucun paramètre des fichiers .editorconfig de niveau supérieur n'est appliqué à cette partie de la base de code, ajoutez la propriété root=true au fichier .editorconfig de niveau inférieur.

    # top-most EditorConfig file for this level
root = true

Les fichiers EditorConfig sont lus de haut en bas. S’il existe plusieurs propriétés portant le même nom, la propriété trouvée le plus récemment avec le même nom prend le pas.

Modifier des fichiers EditorConfig

Visual Studio 2022 fournit un éditeur visuel pour les fichiers EditorConfig.

Après avoir édité votre fichier EditorConfig, vous devez recharger vos fichiers de code pour que les nouveaux paramètres prennent effet.

Visual Studio vous aide à éditer les fichiers EditorConfig en fournissant des listes de complétion IntelliSense. Par exemple :

Capture d'écran montrant IntelliSense dans un fichier EditorConfig.

Si vous éditez de nombreux fichiers EditorConfig, vous pourriez trouver l’extension Service de langage EditorConfig utile. Les fonctionnalités de cette extension incluent notamment une mise en surbrillance de la syntaxe, ainsi que des fonctionnalités IntelliSense, de validation et de mise en forme de code améliorées.

Capture d'écran illustrant IntelliSense avec l'extension du service de langage EditorConfig.

Exemple

L’exemple suivant montre l’état d’indentation d’un extrait de code C# avant et après l’ajout d’un fichier EditorConfig au projet :

  1. Dans la boîte de dialogue Outils>Options, définissez les paramètres de Éditeur de texte>C#>Tabulations pour l’éditeur de texte Visual Studio afin de produire quatre caractères d’espace lors de l’appui sur la touche Tab.

    Capture d'écran montrant le paramètre de Tabs de l'Éditeur de texte.

  2. Comme prévu, lorsque vous appuyez sur la touche Tab sur la ligne suivante, elle indente la ligne en ajoutant quatre caractères d’espace blanc.

    Capture d'écran montrant la touche Tab ajoutant des espaces dans le code.

    Capture d'écran montrant la touche Tab ajoutant des espaces dans le code.

  3. Utilisez EditorConfig pour changer le paramètre des tabulations pour utiliser des tabulations.

    Sélectionnez Utiliser des tabulations dans le fichier EditorConfig.

    Capture d'écran montrant la configuration de l'utilisation des Tabs pour la touche TAB.

    Ajoutez un nouveau fichier nommé .editorconfig au projet, avec le contenu suivant. L’indicateur [*.cs] signifie que ce changement s’applique uniquement aux fichiers de code C# dans le projet.

    # Top-most EditorConfig file
root = true

# Tab indentation
[*.cs]
indent_style = tab

  4. Lorsque vous appuyez sur la touche Tab, des caractères de tabulation apparaissent désormais à la place des espaces.

    Capture d'écran montrant la touche Tab ajoutant des Tabs dans le code.

    Capture d'écran montrant la touche Tab ajoutant des Tabs dans le code.

Résoudre les problèmes liés aux paramètres d’EditorConfig

Si un fichier EditorConfig existe quelque part dans la structure de répertoires au-dessus de l’emplacement de votre projet, Visual Studio applique les paramètres de l’éditeur de ce fichier à votre éditeur. Dans ce cas, le message suivant peut s’afficher dans la barre d’état :

User preferences for this file type are overridden by this project's coding conventions.

Cela signifie que si des paramètres de l’éditeur dans Outils>Options>Éditeur de texte (comme la taille et le style d’indentation, la taille des onglets ou les conventions de codage) sont spécifiés dans un fichier EditorConfig au niveau du projet ou au-dessus dans la structure de répertoires, les conventions du fichier EditorConfig remplacent les paramètres de Éditeur de texte.

Pour résoudre les problèmes d’EditorConfig, suivez ces étapes :

  1. Pour désactiver la prise en charge de l’EditorConfig pour Visual Studio, désactivez l’option Suivre les conventions de codage du projet dans Outils>Options>Éditeur de texte.

    Capture d'écran montrant le paramètre pour suivre les conventions de codage de projet.

  2. Pour trouver des fichiers EditorConfig dans les répertoires parent de votre projet, ouvrez une invite de commandes et exécutez la commande suivante à partir de la racine du disque contenant votre projet.

    dir .editorconfig /s

  3. Pour contrôler la portée de vos conventions EditorConfig, définissez la propriété root=true dans le fichier .editorconfig à la racine de votre référentiel ou dans le répertoire où réside votre projet.

    Visual Studio recherche un fichier nommé .editorconfig dans le répertoire du fichier ouvert et dans chaque répertoire parent. La recherche se termine lorsqu'elle atteint le chemin d'accès au fichier racine, ou si un fichier .editorconfig avec root=true est trouvé.

Contenu connexe