Bereinigen Sie Ihren Code: Wie Sie Ihren eigenen C#-Code-Stil erstellen

Es gibt zwar mehr als eine Möglichkeit, Unity-C#-Code zu formatieren, aber wenn Sie sich auf einen einheitlichen Codestil für Ihr Projekt einigen, kann Ihr Team eine saubere, lesbare und skalierbare Codebasis entwickeln. In diesem Blog stellen wir Ihnen einige Richtlinien und Beispiele vor, die Sie für die Entwicklung und Pflege Ihres eigenen Code Style Guides verwenden können.

Bitte beachten Sie, dass es sich hierbei nur um Empfehlungen handelt, die auf den von Microsoft bereitgestellten Informationen basieren. Dies ist Ihre Chance, sich inspirieren zu lassen und zu entscheiden, was für Ihr Team am besten geeignet ist.

Im Idealfall sollte sich ein Unity-Projekt so anfühlen, als sei es von einem einzigen Autor entwickelt worden, unabhängig davon, wie viele Entwickler tatsächlich daran arbeiten. Ein Styleguide kann Ihnen helfen, Ihren Ansatz zu vereinheitlichen und eine kohärentere Codebasis zu schaffen.

Es ist ratsam, sich so weit wie möglich an Branchenstandards zu orientieren und die vorhandenen Styleguides als Ausgangspunkt für die Erstellung eines eigenen zu nutzen. In Zusammenarbeit mit internen und externen Unity-Experten haben wir ein neues E-Book veröffentlicht: Create a C# style guide: Schreiben Sie sauberen Code, der skaliert zur Inspiration, basierend auf Microsofts umfassendem C#-Stil.

Der Google C# Style Guide ist eine weitere hervorragende Ressource für die Definition von Richtlinien für Benennungs-, Formatierungs- und Kommentierungskonventionen. Auch hier gibt es keine richtige oder falsche Methode, aber wir haben uns für unseren eigenen Leitfaden an den Microsoft-Standards orientiert.

Unser E-Book ist zusammen mit einer C#-Beispieldatei kostenlos erhältlich. Beide Ressourcen konzentrieren sich auf die gebräuchlichsten Coding-Konventionen, die Sie bei der Entwicklung in Unity antreffen werden. Diese sind im Wesentlichen eine Untermenge der Microsoft Framework Design-Richtlinien, die eine Vielzahl von Best Practices enthalten, die über das hinausgehen, was wir in diesem Beitrag behandeln.

Wir empfehlen Ihnen, die Richtlinien in unserem Styleguide an die Präferenzen Ihres Teams anzupassen. Diese Präferenzen sollten unseren Vorschlägen und den Microsoft Framework Design-Richtlinien vorgezogen werden, wenn sie im Widerspruch zueinander stehen.

Die Entwicklung eines Styleguides erfordert eine Vorabinvestition, die sich aber später auszahlt. Die Verwaltung eines einzigen Standardsatzes kann beispielsweise die Zeit reduzieren, die Entwickler für die Umstellung auf ein anderes Projekt benötigen.

Natürlich ist Beständigkeit der Schlüssel. Wenn Sie diese Vorschläge befolgen und Ihren Styleguide in Zukunft ändern müssen, können Sie mit ein paar Such- und Ersetzungsvorgängen Ihre Codebasis schnell migrieren.

Konzentrieren Sie sich darauf, einen pragmatischen Styleguide zu erstellen, der Ihren Bedürfnissen entspricht und die meisten alltäglichen Anwendungsfälle abdeckt. Übertreiben Sie es nicht, indem Sie versuchen, von Anfang an jeden einzelnen Fall zu berücksichtigen. Der Leitfaden wird sich im Laufe der Zeit organisch weiterentwickeln, da Ihr Team ihn von Projekt zu Projekt überarbeitet.

Die meisten Stilrichtlinien enthalten grundlegende Formatierungsregeln. In der Zwischenzeit sind spezifische Namenskonventionen, Richtlinien für die Verwendung von Namespaces und Strategien für Klassen eher abstrakte Bereiche, die mit der Zeit verfeinert werden können.

Sehen wir uns einige gängige Formatierungs- und Benennungskonventionen an, die Sie für Ihren Style Guide in Betracht ziehen könnten.

Die beiden gebräuchlichen Einrückungsstile in C# sind der Allman-Stil, bei dem die öffnenden geschweiften Klammern in eine neue Zeile gesetzt werden (auch bekannt als BSD-Stil von BSD Unix), und der K&R-Stil oder "one true brace style", bei dem die öffnende Klammer in der gleichen Zeile wie die vorherige Überschrift bleibt.

Um die Lesbarkeit zu verbessern, haben wir für unseren Leitfaden den Allman-Stil gewählt, der auf den Microsoft Framework Design-Richtlinien basiert:

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

Welchen Stil Sie auch immer wählen, sorgen Sie dafür, dass jeder Programmierer in Ihrem Team ihn befolgt.

In einem Leitfaden sollte auch angegeben werden, ob geschachtelte mehrzeilige Anweisungen mit geschweiften Klammern versehen werden sollten. Das Entfernen der geschweiften Klammern im folgenden Beispiel führt zwar nicht zu einem Fehler, kann aber beim Lesen verwirrend sein. Deshalb wird in unserem Leitfaden empfohlen, Klammern anzubringen, auch wenn sie optional sind.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

Etwas so Einfaches wie ein horizontaler Abstand kann das Erscheinungsbild Ihres Codes auf dem Bildschirm verbessern. Auch wenn Ihre persönlichen Formatierungsvorlieben variieren können, finden Sie hier einige Empfehlungen aus unserem Style Guide, um die Lesbarkeit zu verbessern:

• Fügen Sie Leerzeichen hinzu, um die Code-Dichte zu verringern: Der zusätzliche Leerraum kann ein Gefühl der visuellen Trennung zwischen Teilen einer Zeile vermitteln.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

• Verwenden Sie zwischen Funktionsargumenten ein einzelnes Leerzeichen nach einem Komma.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

• Fügen Sie nach den Klammern und Funktionsargumenten kein Leerzeichen ein.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

• Verwenden Sie keine Leerzeichen zwischen einem Funktionsnamen und einer Klammer.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

• Leerzeichen innerhalb von Klammern sind zu vermeiden.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

• Verwenden Sie ein einzelnes Leerzeichen vor den Flusskontrollbedingungen: Fügen Sie ein Leerzeichen zwischen dem Flussvergleichsoperator und den Klammern ein.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

• Verwenden Sie ein einzelnes Leerzeichen vor und nach Vergleichsoperatoren.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

Variablen repräsentieren in der Regel einen Zustand, also versuchen Sie, ihren Namen klare und beschreibende Substantive zu geben. Sie können dann Booleschen Variablen, die einen wahren oder falschen Wert angeben müssen, ein Verb voranstellen. Oft sind sie die Antwort auf eine Frage wie "Läuft der Spieler? Ist das Spiel vorbei? Stellen Sie ihnen ein Verb voran, um ihre Bedeutung zu verdeutlichen. Dies ist oft mit einer Beschreibung oder Bedingung verbunden, z. B. isPlayerDead, isWalking, hasDamageMultiplier, usw.

Da Methoden Aktionen ausführen, ist es eine gute Faustregel, ihre Namen mit einem Verb zu beginnen und je nach Rückgabetyp einen Kontext hinzuzufügen, z. B. GetDirection, FindTarget und so weiter. Wenn die Methode einen Rückgabetyp bool hat, kann sie auch als Frage formuliert werden.

Ähnlich wie bei den booleschen Variablen selbst wird den Methoden ein Verb vorangestellt, wenn sie eine Wahr-Falsch-Bedingung zurückgeben. Hier werden sie in Form einer Frage formuliert, z. B. IsGameOver, HasStartedTurn.

Es gibt mehrere Konventionen für die Benennung von Ereignissen und Ereignis-Handles. In unserem Styleguide benennen wir das Ereignis mit einer Verbphrase, ähnlich wie bei einer Methode. Verwenden Sie das Partizip Präsens oder Präteritum, um Ereignisse "vor" oder "nach" anzugeben. Geben Sie zum Beispiel OpeningDoor für ein Ereignis vor dem Öffnen einer Tür und DoorOpened für ein Ereignis danach an.

Wir empfehlen Ihnen auch, Namen nicht abzukürzen. Auch wenn es sich kurzfristig wie ein Produktivitätsgewinn anfühlt, wenn man ein paar Zeichen einspart, kann es sein, dass das, was für Sie jetzt offensichtlich ist, in einem Jahr für einen anderen Teamkollegen nicht mehr gilt. Ihre Variablennamen sollten ihren Zweck verraten und leicht auszusprechen sein. Einbuchstabige Variablen sind für Schleifen und mathematische Ausdrücke geeignet, aber ansonsten sollten Sie Abkürzungen vermeiden. Die Klarheit ist wichtiger als jede Zeitersparnis durch das Weglassen einiger Vokale.

Gleichzeitig sollten Sie eine Variablendeklaration pro Zeile verwenden; das ist weniger kompakt, aber auch weniger fehleranfällig und verbessert die Lesbarkeit. Vermeiden Sie redundante Namen. Wenn Ihre Klasse Player heißt, müssen Sie keine Mitgliedsvariablen namens PlayerScore oder PlayerTarget erstellen. Schneiden Sie sie auf Score oder Target zu.

Eine Praxis, die in unserem Leitfaden hervorgehoben wird, ist, privaten Mitgliedsvariablen einen Unterstrich (_) voranzustellen, um sie von lokalen Variablen zu unterscheiden. Einige Styleguides verwenden Präfixe für private Member-Variablen (m_), Konstanten (k_) oder statische Variablen (s_), damit der Name mehr über die Variable verrät.

Es hat sich jedoch bewährt, den Schnittstellennamen ein großes "I" voranzustellen und danach ein Adjektiv zu verwenden, das die Funktionalität beschreibt. Sie können der Methode zum Auslösen des Ereignisses (im Betreff) sogar "On" voranstellen: Das Subjekt, das das Ereignis aufruft, tut dies in der Regel über eine Methode mit dem Präfix "On", z. B. OnOpeningDoor oder OnDoorOpened.

Unbekannter Blocktyp "codeBlock", bitte geben Sie einen Serializer dafür in der `serializers.types` prop an

Camel Case und Pascal Case sind gängige Standards, die im Vergleich zu Snake oder Kebab Case oder ungarischen Schreibweisen verwendet werden. Unser Leitfaden empfiehlt die Pascal-Schreibweise für öffentliche Felder, Enums, Klassen und Methoden und die Camel-Schreibweise für private Variablen, da dies in Unity gängige Praxis ist.

Es gibt noch viele weitere Regeln zu beachten, die hier nicht behandelt werden. Das Beispielhandbuch und unser neues E-Book, Erstellen Sie einen C#-Styleguide: Schreiben Sie saubereren Code, der skalierbar ist, und geben Sie viele weitere Tipps für eine bessere Organisation.

Das Konzept des sauberen Codes zielt darauf ab, die Entwicklung skalierbarer zu machen, indem eine Reihe von Produktionsstandards eingehalten wird. Ein Styleguide sollte den meisten Entwicklern das Rätselraten über die zu beachtenden Konventionen abnehmen. Letztendlich soll dieser Leitfaden Ihrem Team dabei helfen, einen Konsens über Ihre Codebasis herzustellen, um Ihr Projekt zu einer kommerziellen Produktion auszubauen.

Wie umfangreich Ihr Styleguide sein sollte, hängt von Ihrer Situation ab. Es liegt an Ihrem Team zu entscheiden, ob der Leitfaden Regeln für abstraktere, nicht greifbare Konzepte enthalten soll. Dazu könnten Regeln für die Verwendung von Namespaces, die Aufteilung von Klassen oder die Implementierung von Direktiven wie der #region-Direktive gehören (oder auch nicht). Während #region Ihnen dabei helfen kann, Codeabschnitte in C#-Dateien zusammenzufassen und auszublenden, was große Dateien überschaubarer macht, ist es auch ein Beispiel für etwas, das viele Entwickler als Code Smells oder Anti-Patterns betrachten. Daher sollten Sie es vermeiden, strenge Standards für diese Aspekte der Codegestaltung festzulegen. Es muss nicht alles im Leitfaden festgehalten werden - manchmal reicht es aus, im Team zu diskutieren und Entscheidungen zu treffen.

Als wir mit den Experten sprachen, die an der Erstellung unseres Leitfadens mitgewirkt haben, war ihr wichtigster Ratschlag, dass der Code vor allem lesbar sein sollte. Hier finden Sie einige Hinweise, wie Sie das erreichen können:

• Verwenden Sie weniger Argumente: Argumente können die Komplexität Ihrer Methode erhöhen. Indem Sie ihre Anzahl reduzieren, erleichtern Sie das Lesen und Testen der Methoden.
• Vermeiden Sie übermäßige Überlastung: Sie können eine endlose Permutation von Methodenüberladungen erzeugen. Wählen Sie die wenigen aus, die die Art und Weise widerspiegeln, wie Sie die Methode aufrufen werden, und implementieren Sie diese. Wenn Sie eine Methode überladen, vermeiden Sie Verwirrung, indem Sie sicherstellen, dass jede Methodensignatur eine bestimmte Anzahl von Argumenten hat.
• Vermeiden Sie Nebenwirkungen: Eine Methode muss nur das tun, was ihr Name vorgibt. Vermeiden Sie es, etwas außerhalb des Geltungsbereichs zu ändern. Übergeben Sie Argumente nach Möglichkeit als Wert statt als Referenz. Wenn Sie also Ergebnisse über das Schlüsselwort out oder ref zurücksenden, vergewissern Sie sich, dass dies die einzige Aufgabe ist, die Sie mit der Methode erfüllen wollen. Obwohl Nebenwirkungen für bestimmte Aufgaben nützlich sind, können sie zu unbeabsichtigten Folgen führen. Schreiben Sie eine Methode ohne Seiteneffekte, um unerwartetes Verhalten zu vermeiden.

Wir hoffen, dass dieser Blog Ihnen bei der Entwicklung Ihres eigenen Styleguides hilft. Erfahren Sie mehr in unserer C#-Beispieldatei und unserem brandneuen E-Book, in dem Sie die von uns vorgeschlagenen Regeln überprüfen und an die Präferenzen Ihres Teams anpassen können.

Die Einzelheiten der einzelnen Regeln sind weniger wichtig als die Tatsache, dass sich alle darauf einigen, sie konsequent zu befolgen. Verlassen Sie sich im Zweifelsfall auf den sich entwickelnden Leitfaden Ihres Teams, um Unstimmigkeiten über den Stil zu klären. Schließlich handelt es sich um eine Gruppenarbeit.