Nettoyez votre code : Comment créer votre propre style de code C#
Bien qu'il existe plusieurs façons de formater le code Unity C#, convenir d'un style de code cohérent pour votre projet permet à votre équipe de développer une base de code propre, lisible et évolutive. Dans ce blog, nous fournissons quelques lignes directrices et exemples que vous pouvez utiliser pour développer et maintenir votre propre guide de style de code.
Veuillez noter qu'il s'agit uniquement de recommandations basées sur celles fournies par Microsoft. C'est votre chance de vous inspirer et de décider de ce qui fonctionne le mieux pour votre équipe.
Idéalement, un projet Unity devrait donner l'impression qu'il a été développé par un seul auteur, quel que soit le nombre de développeurs qui y travaillent réellement. Un guide de style peut vous aider à unifier votre approche pour créer une base de code plus cohérente.
C'est une bonne idée de suivre les normes de l'industrie dans la mesure du possible et de parcourir les guides de style existants comme point de départ pour créer le vôtre. En partenariat avec des experts internes et externes d'Unity, nous avons publié un nouvel e-book, Créer un guide de style C# : Écrivez un code plus propre et évolutif pour l'inspiration, basé sur le style C# complet de Microsoft.
Leguide de style Google C# est une autre excellente ressource pour définir des directives concernant les conventions de dénomination, de formatage et de commentaires. Encore une fois, il n’y a pas de bonne ou de mauvaise méthode, mais nous avons choisi de suivre les normes Microsoft pour notre propre guide.
Notre livre électronique, ainsi qu'un exemple de fichier C#, sont disponibles gratuitement. Les deux ressources se concentrent sur les conventions de codage les plus courantes que vous rencontrerez lors du développement dans Unity. Il s’agit essentiellement d’un sous-ensemble des directives de conception de Microsoft Framework, qui incluent un grand nombre de bonnes pratiques au-delà de ce que nous abordons dans cet article.
Nous vous recommandons de personnaliser les directives fournies dans notre guide de style en fonction des préférences de votre équipe. Ces préférences doivent être prioritaires par rapport à nos suggestions et aux directives de conception de Microsoft Framework si elles sont en conflit.
Le développement d’un guide de style nécessite un investissement initial mais sera rentable plus tard. Par exemple, la gestion d’un seul ensemble de normes peut réduire le temps que les développeurs passent à se mettre au travail s’ils passent à un autre projet.
Bien sûr, la cohérence est essentielle. Si vous suivez ces suggestions et devez modifier votre guide de style à l’avenir, quelques opérations de recherche et de remplacement peuvent rapidement migrer votre base de code.
Concentrez-vous sur la création d’un guide de style pragmatique qui correspond à vos besoins en couvrant la majorité des cas d’utilisation quotidiens. Ne tentez pas de prendre en compte chaque cas particulier dès le départ. Le guide évoluera de manière organique au fil du temps, à mesure que votre équipe l'utilisera d'un projet à l'autre.
La plupart des guides de style incluent des règles de formatage de base. Parallèlement, les conventions de dénomination spécifiques, la politique d’utilisation des espaces de noms et les stratégies pour les classes sont des domaines quelque peu abstraits qui peuvent être affinés au fil du temps.
Examinons quelques conventions de formatage et de dénomination courantes que vous pourriez envisager pour votre guide de style.
Les deux styles d'indentation courants en C# sont le style Allman, qui place les accolades ouvrantes sur une nouvelle ligne (également connu sous le nom de style BSD de BSD Unix), et le style K&R, ou « style à une seule vraie accolade », qui maintient l'accolade ouvrante sur la même ligne que l'en-tête précédent.
Dans un souci d'amélioration de la lisibilité, nous avons choisi le style Allman pour notre guide, basé sur les directives de conception de Microsoft Framework :
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
Quel que soit le style que vous choisissez, assurez-vous que chaque programmeur de votre équipe le suit.
Un guide doit également indiquer si les accolades des instructions multilignes imbriquées doivent être incluses. Bien que la suppression des accolades dans l'exemple suivant ne génère pas d'erreur, sa lecture peut être déroutante. C'est pourquoi notre guide recommande d'utiliser des accolades pour plus de clarté, même si elles sont facultatives.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
Quelque chose d'aussi simple que l'espacement horizontal peut améliorer l'apparence de votre code à l'écran. Bien que vos préférences de formatage personnelles puissent varier, voici quelques recommandations de notre guide de style pour améliorer la lisibilité globale :
- Ajoutez des espaces pour réduire la densité du code : les espaces supplémentaires peuvent donner une impression de séparation visuelle entre les parties d'une ligne
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
- Utilisez un seul espace après une virgule, entre les arguments de fonction.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
- N'ajoutez pas d'espace après les parenthèses et les arguments de fonction.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
- N'utilisez pas d'espaces entre le nom d'une fonction et les parenthèses.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
- Évitez les espaces entre parenthèses.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
- Utilisez un seul espace avant les conditions de contrôle de flux : Ajoutez un espace entre l’opérateur de comparaison de flux et les parenthèses.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
- Utilisez un seul espace avant et après les opérateurs de comparaison.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
Les variables représentent généralement un état, essayez donc d’attribuer des noms clairs et descriptifs à leurs noms. Vous pouvez ensuite préfixer les booléens avec un verbe pour les variables qui doivent indiquer une valeur vraie ou fausse. Souvent, ils constituent la réponse à une question telle que : le joueur court-il ? Le jeu est-il terminé ? Préfixez-les avec un verbe pour clarifier leur sens. Ceci est souvent associé à une description ou une condition, par exemple, isPlayerDead, isWalking, hasDamageMultiplier, etc.
Étant donné que les méthodes exécutent des actions, une bonne règle empirique consiste à commencer leur nom par un verbe et à ajouter du contexte si nécessaire, par exemple GetDirection, FindTarget, etc., en fonction du type de retour. Si la méthode a un type de retour booléen, elle peut également être formulée comme une question.
Tout comme les variables booléennes elles-mêmes, préfixez les méthodes avec un verbe si elles renvoient une condition vrai-faux. Cela les formule sous forme de question, par exemple, IsGameOver, HasStartedTurn.
Il existe plusieurs conventions pour nommer les événements et les poignées d'événements. Dans notre guide de style, nous nommons l'événement avec une phrase verbale, similaire à une méthode. Choisissez un nom qui communique avec précision le changement d’état. Utilisez le participe présent ou passé pour indiquer les événements « avant » ou « après ». Par exemple, spécifiez OpeningDoor pour un événement avant d’ouvrir une porte et DoorOpened pour un événement après.
Nous vous recommandons également de ne pas abréger les noms. Même si sauver quelques personnages peut sembler être un gain de productivité à court terme, ce qui est évident pour vous aujourd'hui pourrait ne plus l'être dans un an pour un autre coéquipier. Les noms de vos variables doivent révéler leur intention et être faciles à prononcer. Les variables à une seule lettre conviennent aux boucles et aux expressions mathématiques, mais sinon, vous devez éviter les abréviations. La clarté est plus importante que le temps gagné en omettant quelques voyelles.
En même temps, utilisez une déclaration de variable par ligne ; c'est moins compact, mais aussi moins sujet aux erreurs et améliore la lisibilité. Évitez les noms redondants. Si votre classe s'appelle Player, vous n'avez pas besoin de créer des variables membres appelées PlayerScore ou PlayerTarget. Réduisez-les à Score ou Target.
De plus, évitez trop de préfixes ou d'encodages spéciaux. Une pratique mise en évidence dans notre guide consiste à préfixer les variables membres privées avec un trait de soulignement (_) pour les différencier des variables locales. Certains guides de style utilisent des préfixes pour les variables membres privées (m_), les constantes (k_) ou les variables statiques (s_), de sorte que le nom en révèle plus sur la variable.
Cependant, il est recommandé de préfixer les noms d'interface avec un « I » majuscule et de le suivre d'un adjectif décrivant la fonctionnalité. Vous pouvez même préfixer la méthode de déclenchement de l'événement (dans l'objet) avec « On » : Le sujet qui invoque l'événement le fait généralement à partir d'une méthode préfixée par « On », par exemple, OnOpeningDoor ou OnDoorOpened.
Type de bloc inconnu « codeBlock », veuillez spécifier un sérialiseur pour celui-ci dans la propriété « serializers.types »
Le cas Camel et le cas Pascal sont des normes couramment utilisées, par rapport au cas Snake ou Kebab, ou aux notations hongroises. Notre guide recommande le cas Pascal pour les champs publics, les énumérations, les classes et les méthodes, et le cas Camel pour les variables privées, car c'est une pratique courante dans Unity.
Il existe de nombreuses règles supplémentaires à prendre en compte en dehors de ce qui est abordé ici. Le guide d'exemples et notre nouvel e-book, Créer un guide de style C# : Écrivez un code plus propre et évolutif, fournissent de nombreux autres conseils pour une meilleure organisation.
Le concept de code propre vise à rendre le développement plus évolutif en se conformant à un ensemble de normes de production. Un guide de style devrait éliminer la plupart des conjectures que les développeurs auraient autrement concernant les conventions à suivre. En fin de compte, ce guide devrait aider votre équipe à établir un consensus autour de votre base de code pour faire de votre projet une production à l’échelle commerciale.
Le degré d’exhaustivité de votre guide de style dépend de votre situation. C'est à votre équipe de décider si elle souhaite que son guide établisse des règles pour des concepts plus abstraits et intangibles. Cela pourrait inclure des règles d'utilisation des espaces de noms, la décomposition des classes ou l'implémentation de directives telles que la directive #region (ou non). Bien que #region puisse vous aider à réduire et à masquer des sections de code dans les fichiers C#, rendant ainsi les fichiers volumineux plus gérables, c'est également un exemple de quelque chose que de nombreux développeurs considèrent comme des odeurs de code ou des anti-modèles. Par conséquent, vous souhaiterez peut-être éviter de définir des normes strictes pour ces aspects du style de code. Il n’est pas nécessaire de tout décrire dans le guide : il suffit parfois de discuter et de prendre des décisions en équipe.
Lorsque nous avons discuté avec les experts qui ont contribué à créer notre guide, leur principal conseil était la lisibilité du code avant tout. Voici quelques conseils pour y parvenir :
- Utilisez moins d’arguments : Les arguments peuvent augmenter la complexité de votre méthode. En réduisant leur nombre, vous rendez les méthodes plus faciles à lire et à tester.
- Évitez les surcharges excessives : Vous pouvez générer une permutation infinie de surcharges de méthodes. Sélectionnez les quelques éléments qui reflètent la manière dont vous appellerez la méthode, puis implémentez-les. Si vous surchargez une méthode, évitez toute confusion en vous assurant que chaque signature de méthode possède un nombre distinct d'arguments.
- Éviter les effets secondaires : Une méthode doit simplement faire ce que son nom annonce. Évitez de modifier quoi que ce soit en dehors de sa portée. Transmettez les arguments par valeur plutôt que par référence lorsque cela est possible. Ainsi, lorsque vous renvoyez des résultats via le mot-clé out ou ref, vérifiez qu'il s'agit bien de la seule chose que vous souhaitez que la méthode accomplisse. Bien que les effets secondaires soient utiles pour certaines tâches, ils peuvent entraîner des conséquences imprévues. Écrivez une méthode sans effets secondaires pour réduire les comportements inattendus.
Nous espérons que ce blog vous aidera à démarrer le développement de votre propre guide de style. Apprenez-en plus grâce à notre exemple de fichier C# et à notre tout nouvel e-book où vous pouvez consulter nos règles suggérées et les personnaliser selon les préférences de votre équipe.
Les spécificités des règles individuelles sont moins importantes que le fait que tout le monde accepte de les suivre systématiquement. En cas de doute, fiez-vous au guide évolutif de votre équipe pour régler tout désaccord de style. Après tout, c’est un effort de groupe.
