Quel est un bon nom pour ma classe ou ma variable ? Quels sont les règles à respecter et les écueils à éviter ?
Bien nommer les différents éléments de sa solution logicielle est une stratégie payante sur le long terme. Ça facilite la collaboration entre plusieurs développeurs, ça permet de plus facilement s’y retrouver soi-même, et ça donne surtout de la cohérence à votre code. Quand un code respecte les standards de nommage, tout ce qui peut s’y passer est prévisible. Ça rend sa maintenance et son évolution plus aisées.
À noter avant de commencer : il s’agit de conventions avant tout. Ne pas les respecter ne va pas empêcher votre programme de fonctionner (tout au plus, vous aurez un avertissement de la part de votre IDE). Mais prendre de bonnes habitudes pour avoir un code propre, ça vaut le coup !
Et bien sûr, ici nous nous intéressons au cas du C# .NET. D’autres langages peuvent avoir des conventions différentes.
Dans cet article
Format des identifiants : camelCase, PascalCase, snake case et notation hongroise
Avant de parler des cas de figure en eux-même, rappelons les conventions de casse typique :
- Le PascalCase : chaque mot différent commence par une majuscule, ce qui permet de voir aisément où est chaque mot différent. Il est aussi appelé le Upper Camel Case.
Exemples : FileName, BoxerDog, BlackCoffee, Sun. - Le camelCase : c’est en fait la version plus généraliste du PascalCase, où le premier mot est écrit en minuscule.
Exemples : fileExtension, bassetHound, greenTea, moon. - Le snake_case : consiste à écrire tous les mots en minuscules, séparés par un underscore.
Exemples : file_directory, fox_terrier, herbal_tea, star.
À cela s’ajoute la notation hongroise, ce n’est pas tout à fait une modification de casse, mais qui consiste à ajouter des lettres voire des underscore en début d’une variable pour préciser ses caractéristiques, sa portée, etc. Par exemple, pour une variable contenant l’âge, on écrira iAge (i pour dire que c’est entier), ou une variable membre sera préfixée par « m_ ».
La consigne officielle est claire : les variables en C# ne doivent pas contenir de caractères non alphanumériques. Oublions donc le snake_case.
La notation hongroise est également proscrite, car le type des variables est déjà vérifié par le compilateur et par les IDE modernes. Ça complique donc inutilement la lecture du code.
On utilisera donc exclusivement le PascalCase et le camelCase.
Cas particulier : les variables de préprocesseur sont toutes en majuscules, et peuvent donc être séparées par des underscore pour distinguer les mots. Par exemple, la variable UNITY_EDITOR.
#if UNITY_EDITOR
Debug.Log("This happens only while using Play mode in Unity Editor");
// Do Something
#endifConventions de nommage C# .NET
La règle globale est simple à retenir : quasiment tout commence par une majuscule (donc, en utilisant du PascalCase) hormis les paramètres et les variables privées.
En cas d’incertitude, utiliser le PascalCase. C’est ce qui correspond à la grande majorité des cas. Votre IDE saura vous dire s’il faut mettre une minuscule au départ.
Il faut toujours favoriser la lisibilité du nom, plutôt que chercher à le raccourcir. Il faut que le nom décrive la classe, la variable, la méthode, le plus fidèlement possible, et en ayant du sens lorsqu’on lit le code.
Voici une liste de conventions avec des exemples
| Bonne pratique | Exemple | Contre-exemple |
|---|---|---|
| Prescrire les abréviations | GetSource() MainWeapon | GetSrc() MainWpn |
| Utiliser des noms en anglais US | SellerData PlayableCharacter | DataVendeur PersonnageJouable |
| Classes et structures : noms ou groupes nominaux | Customer Hero UsableItem | |
| Interfaces : la lettre I (i majuscule) suivie d’un adjectif (ou occasionnellement un nom) | IRecordable | Records |
| Méthode : utiliser un verbe, une action | CompareTo(…) Displace(…) Reload(…) | |
| Propriétés : utiliser un nom, une phrase nominale ou un adjectif. | Name Experience | GetStatus() |
| Collections : utiliser un terme descriptif indiquant ce qu’il y a dans la collection, plutôt que le nom d’un élément suivi de « List » ou « Collection » | Characters Party | CharacterList |
| Booléens : utiliser une phrase affirmative, jamais négative. Préfixer avec « Is », « Can », « Has », si ça apporte du sens. | Alive = true CanMove = false IsReady = true HasPayed = false | CantMove = false Payed = false |
| Évènements : utiliser des verbes (puisque ce sont des méthodes) mais conjugués (au présent ou au passé simple) pour indiqué quand l’évènement se produit. | Clicked Painting Landed | AfterLand AfterClick BeforeJump |
En cas de doutes sur la manière de nommer les variables dans des cas spécifique, la documentation officielle de Microsoft « Naming Guidelines » contient de nombreuses autres conventions et exemples, tous les « Do » et les « Don’t ».
Les particularités d’Unity 3D, et comment nommer vos propres classes
En utilisant Unity, vous vous rendrez compte que l’ensemble de ces règles n’est pas forcément respecté par le moteur. Sur des composants de base, vous trouverez notamment des méthodes ou des propriétés publiques qui sont en camelCase (alors que nous avons vu que ça devrait toujours être en PascalCase). Cet état de fait lié à diverses raisons, parmi lesquelles l’âge du moteur (Unity a été lancé en juin 2005, la base de code est énorme), et la volonté d’être proche d’autres systèmes qui utilisent le camelCase comme base (le scripting de shaders ou le C++).
En ce qui concerne vos propres scripts et classes C#, c’est à vous de positionner le curseur entre le respect strict des règles de C# .NET édictées par Microsoft et les particularités d’Unity. Personnellement, je suis partisan de suivre la convention officielle. On prend assez vite le pli de jongler entre les scripts maison qui suivent la convention et ceux d’Unity.
Dans tous les cas, j’ai constaté que certaines habitudes de nommages pour les scripts / classes C# étaient partagées par de nombreux développeurs Unity 3D. Il ne s’agit pas d’une norme officielle, mais de bonnes habitudes à prendre, qui encore une fois vous apporteront de la lisibilité dans votre projet ! Les voici.
- SomethingManager : associé aux script qui gèrent une tâche spécifique dans l’application et qui n’existent qu’en une seule instance.
CameraManager, SaveManager, AchievementManager, MissionManager - SomethingController : script qui contrôlent un GameObject (présent une ou plusieurs fois sur la scène)
PlayerController, EnemyController, DoorController - SomethingGenerator : pour les scripts qui créent des instances de GameObject sur la scène.
PowerUpGenerator, AmmoGenerator, WeaponGenerator - SomethingSettings : pour les scripts qui héritent de la classe ScriptableObjects (qui permet de créer des conteneurs de données)
WorldSettings, AchivementSettings - SomethingEditor, SomethingEditorWindow : pour les scripts qui héritent de la classe Editor ou EditorWindow de Unity (qui permet de créer des inspecteurs ou éditeurs personnalisés)
CharacterGeneratorEditor, WorldSettingsEditor - SomethingCanvas, SomethingText, SomethingButton : pour les scripts liés à l’UI / l’interface (le suffixe doit parler de lui-même)
Voilà de bonnes bases pour bien nommer les méthodes, les propriétés, et même les scripts C# dans Unity. Mais il y a tout un autre domaine à explorer : l’organisation et le nommage des différents assets dans un projet Unity (qu’il s’agisse de modèles 3D, de textures, de sons…). Et comme c’est particulièrement spécifique, ces conventions de nommage feront l’objet de leur propre article !
One thought on “Guide de nommage des variables, méthodes et autres identifiants en C# et dans Unity”