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

  • Article

Pour imposer des styles de codage cohérents à tous ceux qui travaillent dans une base de code, vous pouvez ajouter un fichier EditorConfig à votre solution ou projet. Les paramètres du fichier EditConfig suivent 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. C’est un composant portable qui accompagne votre code et peut appliquer des styles de codage même en dehors de Visual Studio.

Dans Visual Studio, les paramètres du fichier EditorConfig ont priorité sur les paramètres globaux de l’éditeur de texte (accessibles en sélectionnant Éditeur de texte dans la boîte de dialogue Outils>Options). Vous pouvez donc personnaliser chaque base de code pour utiliser des paramètres de l’éditeur de texte qui sont propres au projet. Lorsque vous utilisez des fichiers EditorConfig, vous pouvez toujours continuer à définir vos propres préférences d’éditeur personnel dans l’éditeur de texte 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.

Remarque

Cette rubrique s’applique à Visual Studio pour Windows. Pour Visual Studio pour Mac, veuillez consulter la rubrique Créer et modifier un fichier EditorConfig personnalisé dans Visual Studio pour Mac.

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.

Parce qu’un fichier .editorconfig dans la base de code contient les paramètres de l’EditorConfig, ils voyagent avec cette 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 dans votre projet ou votre solution un dossier auquel 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, qui s’ouvre dans l’éditeur sous 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 de votre hiérarchie de fichiers, ses paramètres s’appliquent à tous les fichiers applicables à ce niveau et en dessous. 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 entièrement ou partiellement des paramètres EditorConfig, ajoutez un fichier .editorconfig au niveau de la hiérarchie de fichiers à laquelle vous voulez appliquer ces paramètres de remplacement. 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 voulez remplacer une partie des paramètres seulement, il suffit de spécifier ces paramètres dans le fichier .editorconfig. Seules les propriétés que vous répertoriez explicitement dans le fichier .editorconfig de niveau inférieur sont remplacées. Les autres paramètres de tous les fichiers .editorconfig de niveau supérieur continuent de s’appliquer.

  • Si vous souhaitez 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 dépôt 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 quand il atteint le chemin racine, ou si un fichier .editorconfig avec root=true est trouvé.

Contenu connexe