Tipps für Namensgebung und Codestil für C#-Scripting in Unity

Diese Website wurde aus praktischen Gründen für Sie maschinell übersetzt. Die Richtigkeit und Zuverlässigkeit des übersetzten Inhalts kann von uns nicht gewährleistet werden. Sollten Sie Zweifel an der Richtigkeit des übersetzten Inhalts haben, schauen Sie sich bitte die offizielle englische Version der Website an.

Klicken Sie hier.

Es gibt zwar keinen richtigen Weg, Ihren C#-Code zu formatieren, aber die Einigung auf einen einheitlichen Stil in Ihrem Team kann zu einer saubereren, lesbareren und skalierbareren Codebasis führen. Eine gut organisierte Stilanleitung kann Ihnen helfen, Diskrepanzen einzudämmen, um ein zusammenhängendes Endprodukt zu erstellen.

Die Namen Ihrer Variablen, Klassen und Methoden sind keine bloßen Bezeichnungen. Sie tragen Gewicht und Bedeutung. Ein guter Namensstil beeinflusst, wie jemand, der Ihr Programm liest, die Idee, die Sie vermitteln möchten, verstehen kann.

Auf dieser Seite finden Sie Tipps und wichtige Überlegungen, die Sie bei der Erstellung Ihrer eigenen Stilanleitung für Namenskonventionen und Codeformatierungen beachten sollten.

Hinweis: Die hier vorgestellten Empfehlungen basieren auf den Empfehlungen von Microsoft. Die besten Code-Style-Guide-Regeln sind diejenigen, die für die Anforderungen Ihres Teams am besten geeignet sind.

Ein Beispiel für eine Code-Stilanleitung finden Sie hier oder Sie laden das vollständige E-Book „Use a C# style guide for clean and scalable game code (Unity 6-Edition)“ herunter.

Identifikationsnamen

Eine Kennung ist jeder Name, den Sie einem Typ (Klasse, Schnittstelle, Struktur, Delegat oder Enum), Mitglied, Variable oder Namensraum zuweisen.

Vermeiden Sie Sonderzeichen (Backslashes, Symbole, Unicode-Zeichen) in Ihren Kennungen, obwohl C# dies zulässt. Diese können bestimmte Unity Befehlszeilentools stören. Vermeiden Sie ungewöhnliche Charaktere, um die Kompatibilität mit den meisten Plattformen zu gewährleisten.

Fallterminologie

Sie können keine Variablen mit Leerzeichen im Namen definieren, da C# das Leerzeichen verwendet, um Kennungen zu trennen. Großbuchstabensysteme können das Problem lindern, zusammengesetzte Namen oder Sätze im Quellcode verwenden zu müssen.

Nachfolgend sind einige bekannte Namenskonventionen aufgeführt:

Kamelgehäuse (camelCase)

Als Kamelkappen wird die Praxis bezeichnet, Sätze ohne Leerzeichen oder Satzzeichen zu schreiben und Wörter mit einem einzigen Großbuchstaben zu trennen. Der allererste Buchstabe ist klein geschrieben. Lokale Variablen und Methodenparameter sind Camel Case. Zum Beispiel:

examplePlayerController

maxHealthPoints

endOfFile

Fall Pascal (Fall Pascal)

Pascal-Fall ist eine Variante des Kamelfalls, bei dem der Anfangsbuchstabe groß geschrieben wird. Verwenden Sie dies für Klassen-, öffentliche Felder und Methodennamen in der Entwicklung von Unity. Zum Beispiel:

ExamplePlayerController

MaxHealthPoints

EndOfFile

Schlangenfall (snake_case)

In diesem Fall werden Leerzeichen zwischen Wörtern durch ein Unterstrichzeichen ersetzt. Zum Beispiel:

example_player_controller

max_health_points

end_of_file

Kebab-Fall (Kebab-Fall)

Hier werden Leerzeichen zwischen Wörtern durch Striche ersetzt. Die Wörter erscheinen auf einem „Spieß“ aus Strichzeichen. Zum Beispiel:

example-player-controller

Max-Gesundheitspunkte

Dateiende

naming-conventions-methodology

Der Kebab-Fall wird häufig in Webtechnologien und insbesondere für CSS eingesetzt. Wir empfehlen es auch für die Verwendung mit dem UI Toolkit USS.

Ungarische Schreibweise

Die Variable oder der Funktionsname gibt oft ihre Absicht oder ihren Typ an. Zum Beispiel:

Int iCounter

String strPlayerName

Die ungarische Schreibweise ist eine ältere Konvention und in der Entwicklung von Unity nicht üblich.

Felder und Variablen

Beachten Sie diese Regeln für Ihre Variablen und Felder:

Nutze Substantive für Variablennamen: Variable Namen sollten beschreibend, klar und eindeutig sein, da sie eine Sache oder einen Zustand repräsentieren. Verwenden Sie bei der Benennung also ein Substantiv, außer wenn die Variable vom Typ bool ist (siehe unten).
Präfix Booleans mit einem Verb: Diese Variablen geben einen wahren oder falschen Wert an. Oftmals sind sie die Antwort auf eine Frage wie „Läuft der Spieler? Ist das Spiel vorbei? Setzen Sie ihnen ein Verb voran, um ihre Bedeutung deutlicher zu machen. Oft ist dies mit einer Beschreibung oder Bedingung verbunden, z. B. isDead, isWalking, hasDamageMultiplier usw.
Nutzen Sie aussagekräftige Namen. Nicht abkürzen (es sei denn, es ist Mathematik): Ihre Variablennamen sollten ihre Absicht offenbaren. Wählen Sie Namen, die einfach auszusprechen und zu suchen sind – nicht nur für Ihre Kollegen, sondern auch, um dem Code bei der Verwendung von KI-Tools zusätzlichen Kontext zu geben, da dies zu einer genaueren Codegenerierung und Vorschlägen beitragen kann. Wählen Sie Kennungen aus, die gut lesbar sind. Beispielsweise ist eine Eigenschaft namens HorizontalAlignment besser lesbar als AlignmentHorizontal. Variablen mit einem Buchstaben sind für Schleifen und mathematische Ausdrücke in Ordnung, aber ansonsten nicht abkürzen. Klarheit ist wichtiger als jede Zeit, die durch das Weglassen einiger Vokale gespart wird. Vielleicht sind Sie versucht, beim Prototyping kurze Junk-Namen zu verwenden, aber das spart Ihnen keine Zeit, wenn Sie den Code zu einem späteren Zeitpunkt umgestalten müssen. Wählen Sie von Anfang an aussagekräftige Namen.
Nutzen Sie Pascal Case (MyPropertyName) für öffentliche Felder. Camel Case (myPrivateVariable) für private Variablen verwenden: Als Alternative zu öffentlichen Feldern verwenden Sie Eigenschaften mit einem öffentlichen Getter (siehe Formatierung oben und unten).
Präfixe oder spezielle Codierungen sind zu berücksichtigen: Einige Leitfäden schlagen vor, privaten Mitgliedsvariablen ein Präfix mit einem Unterstrich (_) hinzuzufügen, um sie von lokalen Variablen zu unterscheiden. In unseren Style Guides verwenden wir Präfixe für private Member-Variablen (m_), Konstanten (k_) oder statische Variablen (s_), sodass der Name auf einen Blick mehr über die Variable verrät. So wird beispielsweise aus movementSpeed m_movementSpeed.PascalCase mit dem Präfix m_MovementSpeed zu mischen ist ebenfalls eine Option, wird aber in modernen C# im Allgemeinen weniger verwendet. Verwenden Sie alternativ dieses Schlüsselwort, um zwischen Member- und lokalen Variablen im Kontext zu unterscheiden und das Präfix zu überspringen. Öffentliche Felder und Eigenschaften sind im Allgemeinen nicht mit Präfixen versehen. Lokale Variablen und Parameter verwenden Kamelfall ohne Präfix. Viele Entwickler verzichten darauf und verlassen sich stattdessen auf den Editor. Allerdings unterstützen nicht alle IDEs Hervorhebungen und Farbcodierung, und einige Tools können überhaupt keinen reichhaltigen Kontext anzeigen.
Felder werden automatisch auf ihre Standardwerte initialisiert: Der Standardwert ist normalerweise 0 für numerische Typen wie int, während Referenztypfelder (z. B. Objekte) standardmäßig auf Null initialisiert sind und Boolfelder standardmäßig auf false initialisiert sind. Daher ist es in der Regel unnötig, ein Feld explizit auf seinen Standardwert festzulegen.
Benennen Sie konstante Variablen mit k_ als Präfix und in PascalCase: Dies hilft Konstanten von regulären Variablen oder Eigenschaften zu unterscheiden und erleichtert das Lesen und Warten des Codes.
Konsistente Angabe (oder Auslassung) von Zugangsstufenmodifikatoren: Wenn Sie den Zugriffsmodifikator weglassen, nimmt der Compiler die Zugriffsstufe als privat an. Dies funktioniert gut, aber seien Sie konsistent darin, wie Sie den Standardzugriffsmodifikator weglassen. In den MSFT-Richtlinien wird empfohlen, Private explizit anzugeben, um die Zugriffsebene klar zu machen und Unklarheiten zu vermeiden. Andere Anleitungen besagen, dass Sie redundante Zugriffsspezifikatoren weglassen sollten (lassen Sie „private“ im Type-Scope) und ebenso redundante Initialisatoren weglassen sollten (d. h. kein „= 0“ bei den Ints, „= Null“ bei den Ref-Typen usw.). Denken Sie daran, dass Sie geschützt verwenden müssen, wenn Sie dies später in einer Unterklasse wünschen. Es gilt jedoch allgemein als bewährte Vorgehensweise, Zugangsstufenmodifikatoren festzulegen.
Vorzugslesbarkeit vor Kürze: Wie dieses Beispiel aus der MSFT-Dokumentation zeigt, ist der Eigenschaftsname CanScrollHorizontally besser als ScrollableX (eine obskure Referenz auf die X-Achse).
Verwenden Sie eine variable Deklaration pro Zeile: Es ist weniger kompakt, verbessert aber die Lesbarkeit.
Überflüssige Namen vermeiden: Wenn Ihre Klasse Player heißt, müssen Sie keine Mitgliedsvariablen namens PlayerScore oder PlayerTarget erstellen. Reduzieren Sie sie auf Score oder Target.
Lassen Sie redundante Initialisatoren fallen (d. h. kein '= 0' bei den Ints, '= Null' bei Referenztypen usw.).
Vermeiden Sie Witze oder Wortspiele: Obwohl sie jetzt vielleicht ein Kichern auslösen, halten die infiniteMonkeys- oder dudeWheresMyChar-Variablen nach ein paar Dutzend Lesevorgängen nicht stand, und noch viel wichtiger: Sie verstoßen gegen unser zuvor erklärtes Ziel, einen offenbarenden Kontext zu benennen.
Beschränken Sie die Verwendung des var-Schlüsselworts auf nur implizit eingegebene lokale Variablen, wenn dies die Lesbarkeit verbessert und der Typ offensichtlich ist: Geben Sie an, wann Sie var in Ihrer Stilanleitung verwenden sollen. Viele Entwickler vermeiden beispielsweise var, wenn es den Typ der Variable verschleiert oder bei primitiven Typen außerhalb einer Schleife.

// EXAMPLE: Public and private variables

public float DamageMultiplier = 1.5f;
public float MaxHealth;
public bool IsInvincible;

private bool _isDead;
private float _currentHealth;

// parameters
public void InflictDamage(float damage, bool isSpecialDamage)
{
    // local variable
    int totalDamage = damage;

    // local variable versus public member variable
    if (isSpecialDamage)
    {
    	totalDamage *= DamageMultiplier;
    }

    // local variable versus private member variable
    if (totalDamage > _currentHealth)
    {
        /// ...
    }
}

Enums

Enums sind spezielle Werttypen, die durch einen Satz benannter Konstanten definiert sind. Standardmäßig sind die Konstanten ganze Zahlen, die von Null hochgezählt werden.

Verwenden Sie Pascal case für Enum-Namen und -Werte. Sie können öffentliche Enums außerhalb einer Klasse platzieren, um sie global zu gestalten. Verwenden Sie ein singuläres Substantiv für den Enum-Namen, da es einen einzelnen Wert aus einer Reihe möglicher Werte darstellt. Sie sollten kein Präfix oder Suffix haben.

Hinweis: Bitweise Enums, die mit dem Attribut System.FlagsAttribute markiert sind, bilden die Ausnahme von dieser Regel. Normalerweise pluralisieren Sie diese, da sie mehrere Typen repräsentieren.

// EXAMPLE: Enums use singular nouns …
public enum WeaponType
{
    Knife,
    Gun,
    RocketLauncher, 
    BFG
}

public enum FireMode
{
    None = 0,
    Single = 5,
    Burst = 7,
    Auto = 8, 
}

// EXAMPLE: … but a bitwise enum is plural.

[Flags] 
public enum AttackModes 
{
  // Decimal                          // Binary
   None = 0,                          // 000000
   Melee = 1,                         // 000001
   Ranged = 2,                        // 000010
   Special = 4,                       // 000100

   MeleeAndSpecial = Melee | Special  // 000101
}

Klassen und Schnittstellen

Beachten Sie diese Standardregeln, wenn Sie Ihre Klassen und Schnittstellen benennen:

Verwenden Sie Pascal-Großbuchstaben oder -Phrasen für Klassennamen: Dies unterscheidet Typnamen von Methoden, die mit Verbphrasen benannt werden.
Wenn Sie in einer Datei ein MonoBehaviour haben, muss der Name der Quelldatei übereinstimmen: Es können andere interne Klassen in der Datei vorhanden sein, aber es sollte nur ein MonoBehaviour pro Datei vorhanden sein.
Vorangestellte Schnittstellennamen mit einem Großbuchstaben I: Dann folgt ein Adjektiv, das die Funktionalität beschreibt.

// EXAMPLE: Class formatting
public class ExampleClass : MonoBehaviour
{

    public int PublicField;
    public static int MyStaticField;

    private int _packagePrivate;
    private int _myPrivate;

    private static int _myPrivate;

    protected int _myProtected;

    public void DoSomething()
    {

    }
}

// EXAMPLE: Interfaces
public interface IKillable
{
    void Kill();
}

public interface IDamageable<T>
{
    void Damage(T damageTaken);
}

Methoden

In C# wird jede ausgeführte Anweisung im Kontext einer Methode ausgeführt.

Hinweis: „Funktion“ und „Methode“ werden in der Entwicklung von Unity oft austauschbar verwendet. Da Sie eine Funktion jedoch nicht schreiben können, ohne sie in eine Klasse in C# aufzunehmen, ist „Methode“ der akzeptierte Begriff.

Methoden führen Aktionen aus, wenden Sie also diese Regeln an, um sie entsprechend zu benennen:

Beginnen Sie den Namen mit einem Verb oder Verbphrasen: Bei Bedarf Kontext hinzufügen, z. B. GetDirection, FindTarget usw.
Verwenden Sie Kamelfall für Parameter: Formatieren Sie Parameter, die in das Verfahren übergeben werden, wie lokale Variablen.
Methoden, die bool zurückgeben, sollten Fragen stellen: Ähnlich wie Boolesche Variablen selbst werden Methoden mit einem Verb vorangestellt, wenn sie eine True-False-Bedingung zurückgeben. Dies formuliert sie in Form einer Frage, z. B. IsGameOver, HasStartedTurn.

// EXAMPLE: Methods start with a verb.
public void SetInitialPosition(float x, float y, float z)
{
    transform.position = new Vector3(x, y, z);
}

// EXAMPLE: Methods ask a question when they return bool.
public bool IsNewPosition(Vector3 currentPosition)
{
    return (transform.position == newPosition);
}

Events und Event-Handler

Ereignisse in C# implementieren das Beobachtermuster. Dieses Softwaredesignmuster definiert eine Beziehung, in der ein Objekt, das Subjekt (oder der Herausgeber), eine Liste von abhängigen Objekten, die Beobachter (oder Abonnenten) genannt werden, benachrichtigen kann. So kann das Subjekt Zustandsänderungen an seine Beobachter senden, ohne die beteiligten Objekte eng zu koppeln. Weitere Informationen zur Verwendung des Beobachters und anderer Designmuster in Ihren Unity Projekten finden Sie im E-Book Verbessern Sie Ihren Code mit Designmustern und SOLID.

Verben verwenden

Benennen Sie das Ereignis mit einer Verbphrase. Wählen Sie einen Namen aus, der die Zustandsänderung genau kommuniziert. Verwenden Sie den aktuellen oder vergangenen Teilnehmer, um Ereignisse „vorher“ oder „nachher“ anzugeben. Geben Sie beispielsweise „OpeningDoor“ für eine Veranstaltung vor dem Öffnen einer Tür oder „DoorOpened“ für eine Veranstaltung danach an.

System.Action verwenden

In den meisten Fällen kann der Aktionsdelegierte die für das Gameplay erforderlichen Ereignisse verwalten. Sie können überall 0 bis 16 Eingabeparameter unterschiedlichen Typs mit einem Rückgabetyp für Leerzeichen übergeben. Die Verwendung des vordefinierten Delegaten speichert Code.

Hinweis: Sie können auch den EventHandler oder EventHandler-Delegaten verwenden. Vereinbaren Sie als Team, wie alle Veranstaltungen durchführen werden.

// EXAMPLE: Events 

// using System.Action delegate

public event Action OpeningDoor;    // event before
public event Action DoorOpened;     // event after

public event Action<int> PointsScored;
public event Action<CustomEventArgs> ThingHappened;

Präfixmethode mit „On“

Das Subjekt, das das Ereignis aufruft, tut dies normalerweise über eine Methode, der „On“ vorangestellt ist, z. „OnOpeningDoor“ oder „OnDoorOpened“.

// raises the Event if you have subscribers
public void OnDoorOpened()
{
    DoorOpened?.Invoke();
}

public void OnPointsScored(int points)
{
    PointsScored?.Invoke(points);
}

Präfix mit Name und Unterstrich des Betreffs

Wenn der Betreff „GameEvents“ genannt wird, können Ihre Beobachter eine Methode namens „GameEvents_OpeningDoor“ oder „GameEvents_DoorOpened“ verwenden. Beachten Sie, dass dies die „Event-Handling-Methode“ genannt wird, nicht zu verwechseln mit dem EventHandler-Delegaten.

EventArgs sorgfältig einsetzen

Erstellen Sie benutzerdefinierte EventArgs nur nach Bedarf. Wenn Sie benutzerdefinierte Daten an Ihr Event übergeben müssen, erstellen Sie einen neuen Typ von EventArgs, die entweder von System.EventArgs oder von einer benutzerdefinierten Struktur geerbt werden.

// define an EventArgs if needed

// EXAMPLE: Read-only, custom struct used to pass an ID and Color
public struct CustomEventArgs
{
    public int ObjectID { get; }
    public Color Color { get; }

    public CustomEventArgs(int objectId, Color color)
    {
        this.ObjectID = objectId;
        this.Color = color;
    }
}

Namespaces

Verwenden Sie Namespaces, um sicherzustellen, dass Ihre Klassen, Schnittstellen, Enums usw. nicht mit bestehenden aus anderen Namespaces oder dem globalen Namespace kollidieren. Namespaces können auch Konflikte mit Assets von Drittanbietern aus dem Asset Store verhindern.

Beim Anwenden von Namespaces:

Verwenden Sie PascalCase ohne besondere Symbole oder Unterstriche.
Fügen Sie eine verwendende Direktive am oberen Rand der Datei hinzu, um die wiederholte Eingabe des Namespace-Präfixes zu vermeiden.
Erstellen Sie auch Unternamensräume. Verwenden Sie den dot(.)-Operator, um die Namensebenen einzugrenzen, so dass Sie Ihre Skripts in hierarchische Kategorien einteilen können. Sie können beispielsweise MyApplication.GameFlow, MyApplication.AI, MyApplication.UI usw. erstellen, um verschiedene logische Komponenten Ihres Spiels aufzunehmen.
Es wird allgemein als bewährte Vorgehensweise angesehen, Namespaces zu haben, die die Ordnerstruktur des Projekts widerspiegeln, da sie verwandte Klassen und Komponenten logisch gruppieren, was es auch erleichtert, die Struktur der Codebasis zu finden und zu verstehen.

namespace Enemy 
{
    public class Controller1 : MonoBehaviour 
    {
        ...
    }
    
    public class Controller2 : MonoBehaviour 
    {
        ...
    }
}

Präfixe

Im Code werden diese Klassen als Enemy.Controller1 bzw. Enemy.Controller2 bezeichnet. Fügen Sie eine verwendende Zeile hinzu, um die Eingabe des Präfixes zu sparen:

Nutzung von Enemy;

Wenn der Compiler die Klassennamen Controller1 und Controller2 findet, versteht er, dass Sie Enemy.Controller1 und Enemy.Controller2 meinen.

Wenn das Skript auf Klassen mit demselben Namen aus verschiedenen Namespaces verweisen muss, verwenden Sie das Präfix, um sie zu unterscheiden. Wenn Sie beispielsweise eine Controller1- und Controller2-Klasse im Player-Namespace haben, können Sie Player.Controller1 und Player.Controller2 ausschreiben, um Konflikte zu vermeiden. Andernfalls meldet der Compiler einen Fehler.

Nutzung von Enemy;

Holen Sie sich weitere Tipps zum Codestil

Erfahren Sie hier mehr über die allgemeine Formatierung oder sehen Sie sich das vollständige E-Book an. Sie können sich auch unser Beispiel für Codestilanleitungen ansehen.