Meilleures pratiques de formatage pour le scripting C# dans Unity

Avec la nomination, le formatage aide à réduire les conjectures et améliore la clarté du code. En suivant un guide de style standardisé, les revues de code deviennent moins une question de l'apparence du code et plus une question de ce qu'il fait.

Visez à personnaliser la façon dont votre équipe formatte le code. Considérez chacune des suggestions de formatage de code suivantes lors de la configuration de votre guide de style Unity. Vous pouvez choisir d'omettre, d'élargir ou de modifier ces règles d'exemple pour répondre aux besoins de votre équipe.

Dans tous les cas, réfléchissez à la manière dont votre équipe mettra en œuvre chaque règle de formatage, puis faites en sorte que tout le monde l'applique uniformément. Reportez-vous au guide de style de votre équipe pour résoudre toute divergence. Moins vous pensez au formatage, plus vous pouvez travailler de manière productive – et créative.

Jetons un coup d'œil à quelques directives de formatage.

Une propriété fournit un mécanisme flexible pour lire, écrire ou calculer des valeurs de classe. Les propriétés se comportent comme si elles étaient des variables membres publiques, mais en fait, ce sont des méthodes spéciales appelées accesseurs.

Chaque propriété a une méthode get et set pour accéder à un champ privé, appelé un champ de soutien. De cette façon, la propriété encapsule les données, les cachant des modifications indésirables par l'utilisateur ou des objets externes. Le "getter" et le "setter" ont chacun leur propre modificateur d'accès, permettant à votre propriété d'être lecture-écriture, lecture seule ou écriture seule.

Vous pouvez également utiliser les accesseurs pour valider ou convertir les données (par exemple, pour vérifier que les données correspondent à votre format préféré ou pour changer une valeur en une unité particulière).

La syntaxe des propriétés peut varier, donc votre guide de style devrait définir comment les formater. Voir les exemples suivants pour des conseils sur la façon de garder les propriétés cohérentes dans votre code.

Utilisez des propriétés à corps d'expression pour des propriétés en lecture seule sur une seule ligne (=>): Cela renvoie le champ de soutien privé.

Tout le reste utilise la syntaxe à corps d'expression { get; set; } : Si vous souhaitez simplement exposer une propriété publique sans spécifier de champ de soutien, utilisez la propriété auto-implémentée.

Appliquez la syntaxe à corps d'expression pour les accesseurs set et get. N'oubliez pas de rendre le « setter » privé si vous ne souhaitez pas fournir d'accès en écriture. Alignez la fermeture avec l'accolade d'ouverture pour les blocs de code multilignes.

La sérialisation de script est le processus automatique de transformation des structures de données ou des états d'objet en un format que Unity peut stocker et reconstruire plus tard. Pour des raisons de performance, Unity gère la sérialisation différemment que dans d'autres environnements de programmation.

Les champs sérialisés apparaissent dans l'Inspecteur, mais vous ne pouvez pas sérialiser des champs statiques, constants ou en lecture seule. Ils doivent être soit publics, soit marqués avec l'attribut [SerializeField]. Unity ne sérialise que certains types de champs, alors référez-vous à la documentation pour l'ensemble complet des règles de sérialisation.

Observez ces directives de base lors de l'utilisation de champs sérialisés :

Utilisez l'attribut [SerializeField] : L'attribut SerializeField peut fonctionner avec des variables privées ou protégées pour les faire apparaître dans l'Inspecteur. Cela encapsule mieux les données que de marquer la variable comme publique, et empêche un objet externe d'écraser ses valeurs.

Utilisez l'attribut Range pour définir des valeurs minimales et maximales : L'attribut [Range(min, max)] est pratique si vous souhaitez limiter ce que l'utilisateur peut attribuer à un champ numérique. Il représente également commodément le champ sous forme de curseur dans l'Inspecteur.

Groupez les données dans des classes ou des structures sérialisables pour nettoyer l'Inspecteur : Définissez une classe ou une structure publique et marquez-la avec l'attribut [Serializable]. Définissez des variables publiques pour chaque type que vous souhaitez exposer dans l'Inspecteur.

Référencez cette classe sérialisable depuis une autre classe. Les variables résultantes apparaissent dans des unités réductibles dans l'Inspecteur.

Il existe deux styles d'indentation courants en C# :

Le style Allman, également connu sous le nom de style BSD (provenant de BSD Unix), place les accolades ouvrantes sur une nouvelle ligne.

Le style K&R, ou "vrai style de accolade unique", garde l'accolade ouvrante sur la même ligne que l'en-tête précédent.

Il existe également des variations sur ces styles d'indentation. Les exemples de ce guide utilisent le style Allman des directives de conception du framework Microsoft. Peu importe lequel vous choisissez en tant qu'équipe, assurez-vous que tout le monde suit le même style d'indentation et de accolades. Vous pouvez également essayer les conseils dans les sections suivantes.

L'indentation est généralement de deux ou quatre espaces. Faites en sorte que tout le monde dans votre équipe s'accorde sur un paramètre dans vos préférences d'éditeur sans déclencher une guerre de flammes entre onglets et espaces.

Dans Visual Studio pour Windows, accédez à Outils > Options > Éditeur de texte > C# > Onglets.

Dans Visual Studio pour Mac, accédez à Préférences > Code source > Code source C#. Sélectionnez le Style de texte pour ajuster les paramètres.

Remarque: Visual Studio offre l'option de convertir les onglets en espaces.

N'omettez pas les accolades - même pas pour des instructions sur une seule ligne. Les accolades augmentent la cohérence, ce qui rend votre code plus facile à lire et à maintenir. Dans cet exemple, les accolades séparent clairement l'action, DoSomething, de la boucle.

Si vous devez ajouter une ligne de débogage ou exécuter DoSomethingElse plus tard, les accolades seront déjà en place. Garder la clause sur une ligne séparée vous permet d'ajouter simplement un point d'arrêt.

Ne retirez pas les accolades des instructions multilignes imbriquées. Retirer les accolades dans ce cas ne générera pas d'erreur, mais risque de causer de la confusion. Appliquez des accolades pour plus de clarté, même si elles sont optionnelles.

Le formatage peut varier, alors documentez les préférences de votre équipe dans votre guide de style et standardisez vos switch déclarations en conséquence.

Voici un exemple d'indentation des instructions de cas.

Quelque chose d'aussi simple que l'espacement peut améliorer l'apparence de votre code à l'écran. Bien que les préférences de formatage personnelles puissent varier, considérez les suggestions ci-dessous pour améliorer la lisibilité.

Ajoutez des espaces pour diminuer la densité du code. L'espace supplémentaire donne un sens de séparation visuelle entre les parties d'une ligne.

Utilisez un seul espace après une virgule entre les arguments de fonction.

N'ajoutez pas d'espace après la parenthèse et les arguments de fonction.

N'utilisez pas d'espaces entre un nom de fonction et une parenthèse.

Autant que possible, évitez les espaces à l'intérieur des crochets.

Utilisez un seul espace avant les conditions de contrôle de flux et ajoutez un espace entre l'opérateur de comparaison de flux et les parenthèses.

Utilisez un seul espace avant et après les opérateurs de comparaison.

Gardez les lignes courtes et considérez l'espace horizontal. Décidez d'une largeur de ligne standard (80–120 caractères) et divisez une longue ligne en déclarations plus petites plutôt que de la laisser déborder.

Comme discuté précédemment, essayez de maintenir l'indentation/la hiérarchie. L'indentation de votre code peut augmenter la lisibilité.

N'utilisez pas d'alignement de colonnes à moins que cela ne soit nécessaire pour la lisibilité. Bien que ce type d'espacement aligne les variables, cela peut compliquer l'appariement du type avec le nom.

L'alignement des colonnes, cependant, peut être utile pour les expressions bit à bit ou les structures avec beaucoup de données. Soyez simplement conscient que cela pourrait créer plus de travail pour vous de maintenir l'alignement des colonnes à mesure que vous ajoutez plus d'éléments. Certains auto-formateurs pourraient également changer quelle partie de la colonne est alignée.

Vous pouvez également utiliser l'espacement vertical à votre avantage. Gardez les parties liées du script ensemble et utilisez des lignes vides à votre avantage. Essayez ce qui suit pour organiser votre code de haut en bas :

• Groupez les méthodes dépendantes ou similaires ensemble : Le code doit être logique et cohérent. Gardez les méthodes qui font la même chose côte à côte, afin que quelqu'un lisant votre logique n'ait pas à sauter dans le fichier.
• Utilisez l'espace vertical pour séparer les parties distinctes de votre classe : Par exemple, vous pouvez ajouter deux lignes vides entre :
• Les déclarations de variables et les méthodes
• Les classes et les interfaces
• Les blocs if-then-else (si cela aide à la lisibilité)

Gardez cela au minimum, et si possible, suivez-le dans votre guide de style.

Utilisation des régions dans votre code

La directive #region vous permet de réduire et de cacher des sections de code dans les fichiers C#, rendant les grands fichiers plus gérables et plus faciles à lire.

Cependant, si vous suivez les conseils généraux pour les classes de ce guide, la taille de votre classe devrait être gérable et la directive #region superflue. Divisez votre code en classes plus petites au lieu de cacher des blocs de code derrière des régions. Vous serez moins enclin à ajouter une région si le fichier source est court.

Remarque : De nombreux développeurs considèrent les régions comme des odeurs de code ou des anti-modèles. Décidez en équipe de quel côté du débat vous vous situez.

Ne désespérez pas si ces règles de formatage semblent écrasantes. Les IDE modernes rendent efficace la mise en place et l'application de celles-ci. Vous pouvez créer un modèle de règles de formatage et ensuite convertir vos fichiers de projet d'un coup.

Pour configurer des règles de formatage pour l'éditeur de script :

• Dans Visual Studio pour Windows, accédez à Outils > Options, puis localisez Éditeur de texte > C# > Style de code Formatage.
• Utilisez les paramètres pour modifier les options Général, Indentation, Nouvelles lignes, Espacement et Enveloppement.
• Dans Visual Studio pour Mac, sélectionnez Visual Studio > Préférences, puis accédez à Code source > Formatage de code > Code source C#.
• Sélectionnez le Politique en haut, puis allez à l'onglet Style de texte. Dans l'onglet Format C#, ajustez les paramètres d'indentation, de nouvelles lignes, d'espacement et d'enveloppement.

Pour forcer votre fichier de script à se conformer au guide de style :

• Dans Visual Studio pour Windows, allez à Edit > Avancé > Formater le document (Ctrl + K, Ctrl + D combinaison de touches). Si vous souhaitez uniquement formater les espaces blancs et l'alignement des tabulations, vous pouvez également utiliser Exécuter le nettoyage de code (Ctrl + K, Ctrl + E) en bas de l'éditeur.
• Dans Visual Studio pour Mac, allez à Éditer > Formater le document (Ctrl + I combinaison de touches).

Sur Windows, vous pouvez également partager vos paramètres d'éditeur depuis Outils > Importer et exporter des paramètres. Exportez un fichier avec le formatage de code C# du guide de style, puis demandez à chaque membre de l'équipe d'importer ce fichier.

Visual Studio vous aide à respecter le guide de style. Le formatage devient alors aussi simple que d'utiliser une combinaison de touches.

Remarque: Vous pouvez configurer un EditorConfig fichier (voir ci-dessus) au lieu d'importer et d'exporter les paramètres de Visual Studio. Cela facilite le partage du formatage entre différents IDE. Il a également l'avantage supplémentaire de fonctionner avec le contrôle de version. Voir les options de règles de style de code .NET pour plus d'informations.

Bien que cela ne soit pas spécifique au code propre, assurez-vous de consulter les 10 façons d'accélérer votre flux de travail de programmation dans Unity avec Visual Studio. N'oubliez pas qu'il est plus pratique de formater et de refactoriser du code propre si vous appliquez ces conseils de productivité.