Up to date

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

Richtlinien für den Codestil

Um zu Godots Quellcode beizutragen, ist der nachstehend aufgeführte Style Guide zu befolgen. Einige Punkte werden im Rahmen der Continuous Integration automatisch überprüft und auch die Reviewer werden auf die Erfüllung dieser und weiterer Bedingungen hinweisen. Daher sollte Ihr System wie unten beschrieben eingerichtet sein, um sicherzustellen, dass alle Commits den Richtlinien entsprechen.

C++ und Objective-C

Es gibt keine schriftlichen Richtlinien, aber der Code-Stil, auf den sich die Entwickler geeinigt haben, wird durch den Code-Beautifier clang-format durchgesetzt, der sich für Sie um alle unsere Konventionen kümmert. Um ein paar zu nennen:

  • Einrückung und Ausrichtung sind beide Tabulator-basiert (jeweils ein und zwei Tabulatoren)

  • Ein einziges Leerzeichen vor und nach Mathe- und Zuweisungsoperatoren sowie nach Kommas

  • Pointer- und Referenzoperatoren werden an den Variablen-Identifier und nicht an den Typnamen angehängt

  • Weitere Informationen zu Header-Includes finden Sie weiter unten

Die von clang-format verwendeten Regeln sind in der Datei .clang-format des Godot-Repositorys beschrieben.

Solange Sie sicherstellen, dass Ihr Stil mit dem umgebenden Code übereinstimmt und dass Sie keine abschließenden Leerzeichen oder Einrückungen mit Leerzeichen einführen, sollte alles in Ordnung sein. Wenn Sie jedoch planen, regelmäßig Beiträge zu leisten, raten wir Ihnen dringend, clang-format lokal einzurichten, um alle Ihre Commits zu prüfen und automatisch zu korrigieren.

Warnung

Der Codestil von Godot sollte nicht auf Code von Drittanbietern angewendet werden, d. h. auf Code, der in Godots Quellcode-Baum enthalten ist, aber nicht speziell für unser Projekt geschrieben wurde. Solcher Code stammt in der Regel von verschiedenen Upstream-Projekten mit ihren eigenen Style-Guides (oder ggf. ohne diese), und wir wollen keine Unterschiede einführen, die eine Synchronisation mit Upstream-Repositories erschweren würden.

Code von Drittanbietern ist normalerweise im Ordner thirdparty/ enthalten und kann daher leicht von Formatierungsskripten ausgeschlossen werden. Für die seltenen Fälle, in denen ein Codeschnipsel eines Drittanbieters direkt in eine Godot-Datei eingebunden werden muss, können Sie /* clang-format off */ und /* clang-format on */ verwenden, um clang-format anzuweisen, ein Stück Code zu ignorieren.

Siehe auch

Diese Richtlinien betreffen nur die Formatierung des Codes. Siehe C++-Verwendungsrichtlinien für eine Liste von Sprachfeatures, die in Pull Requests erlaubt sind.

Lokale Verwendung von clang-format

Zuallererst müssen Sie clang-format installieren. Aktuell müssen Sie clang-format 13 verwenden, um mit Godots Format kompatibel zu sein. Spätere Versionen könnten geeignet sein, aber frühere Versionen unterstützen möglicherweise nicht alle verwendeten Optionen oder formatieren einige Dinge anders, was zu Stil-Problemen in Pull Requests führt.

Installation

So wird clang-format installiert:

  • Linux: Normalerweise ist es mit der clang-Toolchain, die in Ihrer Distribution enthalten ist, sofort verfügbar. Wenn Ihre Distribution nicht die notwendige Version enthält, können Sie eine vorkompilierte Version von der LLVM-Website herunterladen, oder wenn Sie ein Debian-Derivat benutzen, verwenden Sie die Upstream-Repos.

  • macOS und Windows: Sie können vorkompilierte Binärdateien von der LLVM Website herunterladen. Möglicherweise müssen Sie den Pfad zum Ordner der Binärdatei zur PATH-Umgebungsvariablen Ihres Systems hinzufügen, um clang-format direkt aufrufen zu können.

Sie haben dann verschiedene Möglichkeiten, das Clang-Format auf Ihre Änderungen anzuwenden:

Manuelle Verwendung

Mit dem folgenden Befehl können Sie clang-format manuell auf eine oder mehrere Dateien anwenden:

clang-format -i <path/to/file(s)>

  • -i bedeutet, dass die Änderungen direkt in die Datei geschrieben werden sollen (standardmäßig würde clang-format die geänderte Version nur in das Terminal ausgeben).

  • Der Pfad kann auf mehrere Dateien zeigen, entweder nacheinander oder mit Platzhaltern wie in einer typischen Unix-Shell. Seien Sie beim Globbing vorsichtig, damit Sie nicht clang-format auf kompilierte Objekte (.o- und .a-Dateien) anwenden, die sich in Godots Dateibaum befinden. Verwenden Sie also lieber core/*.{cpp,h} als core/*.

Pre-Commit-Hook

Zur Vereinfachung bieten wir einen Pre-Commit-Hook für Git an, der über clang-format automatisch alle Ihre Commits prüft, damit Sie die Änderungen in den endgültigen Commit übernehmen können.

Dieser "Hook" ist ein Skript, das in misc/hooks zu finden ist. Lesen Sie die README.md dieses Ordners für die Installationsanweisungen.

Wenn sich Ihr clang-format nicht im PATH befindet, müssen Sie möglicherweise die Datei pre-commit-clang-format bearbeiten, um auf das richtige Binary zu verweisen, damit es funktioniert. Der Hook wurde unter Linux und macOS getestet, sollte aber auch in der Git-Shell unter Windows funktionieren.

IDE Plugin

Die meisten IDEs oder Code-Editoren verfügen über Beautifier-Plugins, die so konfiguriert werden können, dass clang-format automatisch ausgeführt wird, beispielsweise jedes Mal, wenn Sie eine Datei speichern.

Hier ist eine unvollständige Liste von Beautifier-Plugins für einige IDEs:

(Pull Requests sind willkommen, um diese Liste mit getesteten Plugins zu erweitern.)

Header-Includes

Beim Hinzufügen neuer C++ oder Objective-C Dateien oder beim Einfügen neuer Header in vorhandene Dateien, sollten die folgenden Regeln beachtet werden:

  • Die ersten Zeilen in der Datei sollten Godots Copyright-Header und MIT-Lizenz sein, die aus einer anderen Datei kopiert wurden. Achten Sie darauf, den Dateinamen anzupassen.

  • In einem .h-Header sollten Include-Guards in der Form DATEINAME_H verwendet werden.

  • In einer .cpp-Datei (z.B. dateiname.cpp) sollte das erste Include dasjenige sein, in dem die Klasse deklariert wird (z.B. #include "dateiname.h"), gefolgt von einer Leerzeile zur Trennung.

  • Dann kommen Header aus Godots eigener Code-Basis, die in alphabetischer Reihenfolge (erzwungen durch clang-format) mit Pfaden relativ zum Stammverzeichnis eingebunden werden. Diese Includes sollten mit Anführungszeichen eingebunden werden, z.B. #include "core/object.h". Auf den Block der Godot-Header-Includes sollte dann eine Leerzeile zur Trennung folgen.

  • Schließlich kommen Drittanbieter-Header (entweder von thirdparty oder aus den Include-Pfaden des Systems) und sollten mit den Symbolen < und > eingebunden werden, z.B. #include <png.h>. Auf den Block der Drittanbieter-Header sollte ebenfalls eine Leerzeile zur Trennung folgen.

  • Godot- und Drittanbieter-Header sollten in die Datei aufgenommen werden, die sie benötigt, d. h. in den .h-Header, wenn sie im deklarativen Code verwendet werden, oder in die .cpp, wenn sie nur im imperativen Code verwendet werden.

Beispiel:

/**************************************************************************/
/*  my_new_file.h                                                         */
/**************************************************************************/
/*                         This file is part of:                          */
/*                             GODOT ENGINE                               */
/*                        https://godotengine.org                         */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
/*                                                                        */
/* Permission is hereby granted, free of charge, to any person obtaining  */
/* a copy of this software and associated documentation files (the        */
/* "Software"), to deal in the Software without restriction, including    */
/* without limitation the rights to use, copy, modify, merge, publish,    */
/* distribute, sublicense, and/or sell copies of the Software, and to     */
/* permit persons to whom the Software is furnished to do so, subject to  */
/* the following conditions:                                              */
/*                                                                        */
/* The above copyright notice and this permission notice shall be         */
/* included in all copies or substantial portions of the Software.        */
/*                                                                        */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
/**************************************************************************/

#ifndef MY_NEW_FILE_H
#define MY_NEW_FILE_H

#include "core/hash_map.h"
#include "core/list.h"
#include "scene/gui/control.h"

#include <png.h>

...

#endif // MY_NEW_FILE_H

/**************************************************************************/
/*  my_new_file.cpp                                                       */
/**************************************************************************/
/*                         This file is part of:                          */
/*                             GODOT ENGINE                               */
/*                        https://godotengine.org                         */
/**************************************************************************/
/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur.                  */
/*                                                                        */
/* Permission is hereby granted, free of charge, to any person obtaining  */
/* a copy of this software and associated documentation files (the        */
/* "Software"), to deal in the Software without restriction, including    */
/* without limitation the rights to use, copy, modify, merge, publish,    */
/* distribute, sublicense, and/or sell copies of the Software, and to     */
/* permit persons to whom the Software is furnished to do so, subject to  */
/* the following conditions:                                              */
/*                                                                        */
/* The above copyright notice and this permission notice shall be         */
/* included in all copies or substantial portions of the Software.        */
/*                                                                        */
/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,        */
/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF     */
/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY   */
/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,   */
/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE      */
/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                 */
/**************************************************************************/

#include "my_new_file.h"

#include "core/math/math_funcs.h"
#include "scene/gui/line_edit.h"

#include <zlib.h>
#include <zstd.h>

Java

Godots Java-Code (meist in platform/android) wird auch über clang-format erzwungen - siehe die Anweisungen oben, um es einzurichten. Beachten Sie, dass dieser Style-Guide nur für Code gilt, der von Godot geschrieben und gewartet wird, nicht für Code von Drittanbietern wie dem Unterordner java/src/com/google.

Python

Das SCons-Buildsystem von Godot ist in Python geschrieben, und verschiedene im Quellcode-Baum enthaltene Skripte verwenden ebenfalls Python.

Für diese folgen wir dem Black Code Style. "Blacken" Sie ihre eigenen Python-Änderungen mit Black.

Black lokal verwenden

Zuerst müssen Sie Black installieren. Black benötigt zur Ausführung Python 3.7+.

Installation

So wird Black installiert:

pip3 install black --user

Sie haben dann verschiedene Möglichkeiten, Black auf Ihre Änderungen anzuwenden:

Manuelle Verwendung

Sie können Black manuell auf eine oder mehrere Dateien mit dem folgenden Befehl anwenden:

black -l 120 <path/to/file(s)>

  • -l 120 bedeutet, dass die zulässige Anzahl von Zeichen pro Zeile 120 beträgt. Diese Anzahl wurde von den Entwicklern vereinbart.

  • Der Pfad kann auf mehrere Dateien verweisen, entweder nacheinander oder mit Platzhaltern wie in einer typischen Unix-Shell.

Pre-Commit-Hook

Um die Benutzung zu erleichtern, bieten wir einen Pre-Commit-Hook für Git an, der automatisch bei allen Ihren Commits Black zur Überprüfung ausführt und mit dem Sie dessen Änderungen auf das endgültige Commit anwenden können.

Dieser "Hook" ist ein Skript, das unter misc/hooks zu finden ist. In der README.md des Ordners finden Sie Anweisungen zur Installation.

Editor-Integration

Viele IDEs oder Code-Editoren verfügen über Beautifier-Plugins, die so konfiguriert werden können, dass Black automatisch ausgeführt wird, beispielsweise jedes Mal, wenn Sie eine Datei speichern. Weitere Informationen finden Sie unter Black im Editor integrieren.

Style Guide für Kommentare

Dieser Kommentar-Style Guide gilt für alle Programmiersprachen, die innerhalb der Codebasis von Godot verwendet werden.

  • Verwenden Sie am Anfang von Kommentaren ein Leerzeichen, um sie von deaktiviertem Code zu unterscheiden.

  • Verwenden Sie ganze Sätze für Kommentare. Kommentare sollen mit einem Großbuchstaben beginnen und immer mit einem Punkt enden.

  • Referenzieren Sie Variablen-/Funktionsnamen und -werte mit Backticks.

  • Brechen Sie Kommentare bei ~100 Zeichen um.

  • Sie können TODO:, FIXME:, NOTE:, oder HACK: als Ermahnungen verwenden, wenn es nötig ist.

Beispiel:

// Compute the first 10,000 decimals of Pi.
// FIXME: Don't crash when computing the 1,337th decimal due to `increment`
//        being negative.

Wiederholen Sie nicht, was der Code in einem Kommentar sagt. Erklären Sie eher das Warum als das Wie.

Schlecht:

// Draw loading screen.
draw_load_screen();

Sie können Kommentare im Javadoc-Stil über Funktions- oder Makrodefinitionen verwenden. Es wird empfohlen, Kommentare im Javadoc-Stil nur für Methoden zu verwenden, die für Skripting nicht sichtbar sind. Dies liegt daran, dass diese Methoden stattdessen im Klassenreferenz-XML dokumentiert werden sollten.

Beispiel:

/**
 * Returns the number of nodes in the universe.
 * This can potentially be a very large number, hence the 64-bit return type.
 */
uint64_t Universe::get_node_count() {
    // ...
}

Verwenden Sie für Member-Variablen keine Kommentare im Javadoc-Stil, sondern verwenden Sie stattdessen einzeilige Kommentare:

class Universe {
    // The cached number of nodes in the universe.
    // This value may not always be up-to-date with the current number of nodes
    // in the universe.
    uint64_t node_count_cached = 0;
};