Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Leitlinien zum Schreiben

Die Godot-Community ist international, Benutzer kommen aus der ganzen Welt. Einige von ihnen sind jung und viele sprechen Englisch nicht als Muttersprache. Deshalb müssen wir alles in einer klaren und allgemeinverständlichen Sprache schreiben. Für die Klassenreferenz ist es das Ziel, sie für alle leicht lesbar und präzise zu machen.

Knapp zusammengefasst, versuchen Sie sich an folgendes zu halten:

  1. Den Aktiv verwenden

  2. Präzise Tätigkeitsverben verwenden

  3. Verben vermeiden, die auf "-ing" enden

  4. Unnötige Adverbien und Adjektive entfernen.

  5. Diese 8 Wörter vermeiden: obvious, simple, basic, easy, actual, just, clear und however

  6. Explizite Verweise verwenden

  7. 's verwenden, um Besitz anzuzeigen

  8. Das Oxford-Komma verwenden

Hier sind 3 Arten, um Klassen zu beschreiben:

  1. Geben Sie in der Kurzbeschreibung einen Überblick über den Node

  2. Erwähnen Sie, welche Methoden zurückgegeben werden, wenn dies nützlich ist

  3. Verwenden Sie "if true", um Boolesche Werte zu beschreiben

Bemerkung

Die Aufgabe eines technischen Redakteurs ist es, so viele Informationen wie möglich in möglichst kleine und klare Sätze zu packen. Diese Richtlinien helfen Ihnen dabei, auf dieses Ziel hinzuarbeiten.

Siehe auch

Siehe die Inhaltsrichtlinien für Informationen über die Arten von Dokumentation, die Sie in der offiziellen Dokumentation schreiben können.

7 Regeln für klares Englisch

Den Aktiv verwenden

Verwenden Sie wenn möglich den Aktiv. Nehmen Sie die Klassen, Methoden und Konstanten, die Sie beschreiben, als Subjekt. Es mah natürlich sein, im Passiv zu schreiben, aber es ist schwieriger zu lesen und führt zu längeren Sätzen.

Passiv:

The man **was bitten** by the dog.

Aktiv:

The dog bit the man.

Schlecht: Verwenden Sie nicht die passive Form:

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

Gut: Verwenden Sie den Namen des Nodes als Substantiv:

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

Präzise Tätigkeitsverben verwenden

Bevorzugen Sie präzise, aber gebräuchliche Verben gegenüber generischen Verben wie make, set und allen Ausdrücken, die Sie durch ein einziges Wort ersetzen können.

Schlecht: Wiederholen Sie nicht den Namen der Methode. Es wird bereits angegeben, dass der Pivot-Wert auf einen neuen Wert gesetzt wird:

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

Gut: Erklären Sie was die Konsequenz dieses "set" ist: Verwenden Sie präzise Verben wie place, position, rotate, fade, usw.

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

Verben vermeiden, die auf "-ing" enden

Die Verlaufsformen beschreiben kontinuierliche Aktionen. z.B. "is calling", "is moving".

Schlecht: Verwenden Sie nicht die Verlaufsform für sofortige Änderungen.

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

Gut: Verwenden Sie das "Simple Present", "Past" oder "Future".

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

Ausnahme: Wenn das Thema nicht eindeutig ist, führt das Ersetzen von "ing"-Verben nicht zu einer Verbesserung. Zum Beispiel würde im vorherigen Satz "it replaces" nicht viel Sinn machen, wo jetzt "replacing" steht.

Sie können im englischen die Verlaufsform verwenden, um zeitlich kontinuierliche Aktionen zu beschreiben. Alles wie Animationen oder Koroutinen.

Tipp

Verben können sich mit -ing in adjektivische Substantive verwandeln. Dies ist keine Konjugation, also können Sie sie verwenden: the remaining movement, the missing file, usw.

Entfernen Sie unnötige Adverbien und Adjektive

Schreiben Sie so wenig Adjektive und Adverbien wie möglich. Verwenden Sie sie nur, wenn sie der Beschreibung wichtige Informationen hinzufügen.

Schlecht: Verwenden Sie keine überflüssigen oder bedeutungslosen Adverbien. Wörter, welche die Dokumentation verlängern, aber keine Informationen hinzufügen:

**Basically** a big texture [...]

Gut: Schreiben Sie kurze Sätze in einer einfachen, beschreibenden Sprache:

A big texture [...]

Streichen Sie diese 8 Wörter

Schlecht: Benutzen Sie niemals diese 8 gesperrten Wörter:

  1. obvious

  2. simple

  3. basic

  4. easy

  5. actual

  6. just

  7. clear

  8. however (manche Bedeutungen)

Das Erstellen und Programmieren von Spielen ist nicht einfach, und für jemanden, der zum ersten Mal die Verwendung der API lernt, ist nichts einfach. Andere Wörter in der Liste, wie just oder actual, fügen dem Satz keine Informationen hinzu. Verwenden Sie auch keine entsprechenden Adverbien: obviously, simply, basically, easily, actually, clearly.

Schlecht: Beispiel: Die gesperrten Wörter verlängern die Beschreibung und lenken die Aufmerksamkeit von den wichtigsten Informationen ab:

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

Gut: entfernen Sie sie:

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

"Simple" hilft nie. Denken Sie daran, dass für andere Benutzer alles komplex sein oder sie frustrieren kann. Es gibt nichts Schöneres als ein gutes altes it's simple um jemanden erschaudern zu lassen. Hier ist die alte kurze Beschreibung, der erste Satz auf der Seite des Timer-Nodes:

**Timer**
A **simple** Timer node.

Gut: Erklären Sie stattdessen, was der Node tut:

**Timer**
Calls a function of your choice after a certain duration.

Schlecht: Verwenden Sie nicht "basic", es ist zu vage:

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

Gut: Verwenden Sie die kurze Beschreibung, um einen Überblick über den Node zu erhalten:

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

Explizite Verweise verwenden

Bevorzugen Sie explizite Verweise gegenüber impliziten.

Schlecht: Verwenden Sie keine Wörter wie "the former", "the latter" usw. Sie sind im Englischen nicht die gebräuchlichsten und führen dazu, dass man den Bezug noch einmal nachlesen muss.

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

Gut: Wiederholen Sie Wörter. Sie beseitigen alle Unklarheiten:

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

Wenn Sie denselben Variablennamen drei- oder viermal wiederholen müssen, so sollten Sie Ihre Beschreibung wahrscheinlich neu formulieren.

's verwenden, um Besitz anzuzeigen

Vermeiden Sie "The milk of the cow". Es fühlt sich auf Englisch unnatürlich an. Schreiben Sie stattdessen "The cow's milk".

Schlecht: Schreiben Sie nicht "of the X":

The region **of the AtlasTexture that is** used.

Gut: Benutzen Sie 's. Damit können Sie das Hauptthema an den Anfang des Satzes setzen und es kurz halten:

The **AtlasTexture's** used region.

Verwenden Sie das Oxford-Komma bei Aufzählungen

Aus dem Oxford-Wörterbuch:

Das 'Oxford-Komma' ist ein optionales Komma vor dem Wort 'und' am Ende einer Aufzählung: We sell books, videos, and magazines.

[...] Nicht alle Autoren und Verleger verwenden es, aber es kann die Bedeutung eines Satzes verdeutlichen, wenn die Elemente in einer Liste keine einzelnen Wörter sind: These items are available in black and white, red and yellow, and blue and green.

Schlecht: Lassen Sie das letzte Element einer Liste nicht ohne Komma:

Create a CharacterBody2D node, a CollisionShape2D node and a sprite node.

Gut: Fügen Sie ein Komma vor and oder or für das letzte Element einer Liste mit mehr als zwei Elementen ein.

Create a CharacterBody2D node, a CollisionShape2D node, and a sprite node.

Wie man Methoden und Klassen schreibt

Dynamische und statische Typisierung

Die Codebeispiele in der Dokumentation sollten einem einheitlichen Stil folgen, um die Benutzer nicht zu verwirren. Da statische Typhinweise ein optionales Feature von GDScript sind, haben wir uns entschieden, beim Schreiben von dynamischem Code zu bleiben. Dies führt dazu, dass GDScript präzise und zugänglich geschrieben wird.

Die Ausnahme bilden Themen, die Benutzern statische Typisierungskonzepte erläutern.

Schlecht: Fügen Sie keinen Typhinweis mit einem Doppelpunkt oder durch Casting hinzu:

const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite2D as Sprite2D

Gut: Schreiben Sie Konstanten und Variablen mit dynamischer Typisierung:

const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite2D

Schlecht: Schreiben Sie keine Funktionen mit abgeleiteten Argumenten oder Rückgabetypen:

func choose(arguments: PackedStringArray) -> String:
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

Gut: Schreiben Sie Funktionen, die dynamische Typisierung verwenden:

func choose(arguments):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size = arguments.size()
    var choice = randi() % size
    return arguments[choice]

Verwenden Sie, wo es angebracht ist, reale Codebeispiele

Beispiele aus der realen Welt sind für Anfänger leichter zugänglich als abstrakte foos und bars. Sie können sie auch direkt aus Ihren Spieleprojekten kopieren und so sicherstellen, dass jeder Codeschnipsel ohne Fehler kompiliert wird.

Wenn Sie var speed = 10 statt var my_var = 10 schreiben, können Anfänger den Code besser verstehen. Es gibt ihnen einen Bezugsrahmen, in dem sie die Codeschnipsel in einem Live-Projekt verwenden können.

Schlecht: Schreiben Sie keine erfundenen Beispiele:

@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode


func foo():
    # Do stuff

Gut: Schreiben Sie konkrete Beispiele:

@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

Natürlich gibt es Situationen, in denen die Verwendung von Beispielen aus der realen Welt unpraktisch ist. In solchen Situationen sollten Sie trotzdem keine Namen wie my_var, foo() oder my_func() verwenden und sich stattdessen sinnvollere Namen für Ihre Beispiele überlegen.

Geben Sie in der Kurzbeschreibung einen Überblick über den Node

Die Kurzbeschreibung ist der wichtigste Satz der Referenz. Er ist der erste Kontakt des Benutzers mit einem Node:

  1. Sie ist die einzige Beschreibung im Dialogfeld "Neuen Node erstellen".

  2. Sie befindet sich oben auf jeder Seite in der Referenz

Die Kurzbeschreibung sollte die Rolle des Nodes und seine Funktionalität in bis zu 200 Zeichen erklären.

Schlecht: Schreiben Sie keine winzigen und vage Zusammenfassungen:

**Node2D**
Base node for 2D system.

Gut: Geben Sie einen Überblick über die Funktionalität des Nodes:

**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.

Verwenden Sie die vollständige Beschreibung des Nodes, um weitere Informationen und, falls möglich, ein Codebeispiel bereitzustellen.

Erwähnen Sie, welche Methoden zurückgegeben werden, wenn dies nützlich ist

Einige Methoden geben wichtige Werte zurück. Beschreiben Sie diese am Ende der Beschreibung, am besten in einer neuen Zeile. Bei allen Methoden, deren Name mit set oder get beginnt, müssen Sie die Rückgabewerte nicht erwähnen.

Schlecht: Verwenden Sie nicht die passive Form:

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

Gut: Verwenden Sie immer "Returns".

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

Beachten Sie die Ausnahme von der Regel, den Aktiv zu verwenden: Bei der move-Methode kann ein externer Collider die Methode und den Body, der move aufruft, beeinflussen. In diesem Fall können Sie die den Passiv verwenden.

Verwenden Sie "if true", um Boolesche Werte zu beschreiben

Für boolesche Member-Variablen sollten Sie immer if true und/oder if false verwenden, um eindeutig zu bleiben. Controls whether or not kann mehrdeutig sein und wird nicht für jede Member-Variable funktionieren.

Umgeben Sie außerdem boolesche Werte, Variablennamen und Methoden mit [code][/code].

Gut: Fangen Sie mit "if true" an:

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

Verwenden Sie [code] um Argumente herum

In der Klassenreferenz umgeben Sie Argumente immer mit [code][/code]. In der Dokumentation und in Godot wird es dann so angezeigt. Wenn Sie XML-Dateien im Godot-Repository bearbeiten, ersetzen Sie vorhandene Argumente, die 'so' oder `so` geschrieben sind, durch [code]so[/code].

Allgemeines Vokabular für die Godot-Dokumentation

Die Entwickler haben einige spezifische Wörter ausgewählt, um auf Bereiche der Benutzeroberfläche zu verweisen. Sie werden im Quellcode und in der Dokumentation verwendet, und Sie sollten sie immer anstelle von Synonymen verwenden, damit die Benutzer wissen, wovon Sie sprechen.

Übersicht über die Benutzeroberfläche und das allgemeine Vokabular

Übersicht über die Benutzeroberfläche und das allgemeine Vokabular

In der oberen linken Ecke des Editors befinden sich die main menus. In der Mitte ändern die Buttons den workspace. Und zusammen sind die Buttons oben rechts die playtest buttons. Der Bereich in der Mitte, der den 2D- oder 3D-Space anzeigt, liegt der viewport. Oben finden Sie eine Liste der tools innerhalb der toolbar.

Die Tabs oder andockbaren Bereiche auf beiden Seiten des Viewports sind docks. Sie haben das FileSystem dock und das Scene dock, welches Ihren Szenenbaum enthält, das Import dock, das Node dock und den Inspector, auch Inspector dock genannt. Im Default-Layout können Sie die Docks mit Tabs tabs nennen: das Scene tab, das Node tab...

Die Animation, der Debugger usw. am unteren Rand des Viewports sind panels. Zusammen bilden sie die bottom panels.

Ausklappbare Bereiche des Inspektors sind sections. Die Klassennamen des Parent eines Nodes, die man nicht ausklappen kann, sind Classes, z.B. die CharacterBody2D class. Und einzelne Zeilen mit Key-Value-Paaren sind properties. Beispielsweise position oder modulate color sind beides properties.

Richtlinien für Tastenkürzel

Tastatur- und Maus-Eingaben sollten das Tag :kbd: verwenden, mit dem sich Eingaben vom Rest des Textes und des Inline-Codes abheben können. Verwenden Sie das kompakte Formular für Modifikatortasten (Ctrl/Cmd) anstelle der ausgeschriebenen Form (Control/Command). Verwenden Sie für Kombinationen das Symbol + mit einem Leerzeichen auf beiden Seiten des Symbols.

Stellen Sie sicher, dass Sie Verknüpfungen erwähnen, die sich unter MacOS von anderen Plattformen unterscheiden. Unter MacOS ersetzt Cmd häufig Ctrl in Tastaturkürzeln.

Versuchen Sie, das Kürzel so gut wie möglich in Sätze zu integrieren. Hier einige Beispiele, bei denen das Tag :kbd: zur besseren Sichtbarkeit unverändert bleibt:

  • Press :kbd:`Ctrl + Alt + T` to toggle the panel (:kbd:`Cmd + Alt + T` on macOS).

  • Press :kbd:`Space` and hold the left mouse button to pan in the 2D editor.

  • Press :kbd:`Umschalt + Pfeil oben` to move the node upwards by 8 pixels.