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

Godot's code style should not be applied to third-party code, i.e. code that is included in Godot's source tree, but was not written specifically for our project. Such code usually comes from different upstream projects with their own style guides (or lack thereof), and don't want to introduce differences that would make syncing with upstream repositories harder.

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

Sie müssen clang-format 17 verwenden, um mit dem Format von Godot 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 Stilproblemen in Pull Requests führt.

Pre-Commit-Hook

Um die Nutzung zu erleichtern, bieten wir mit dem Python-Framework pre-commit-Hooks für Git an, die clang-format automatisch auf alle Ihre Commits mit der richtigen Version von clang-format anwenden. Zum Einrichten:

pip install pre-commit
pre-commit install

Sie können den Hook auch manuell mit pre-commit run ausführen.

Bemerkung

Zuvor hatten wir einen Hook im Ordner misc/hooks bereitgestellt. Wenn Sie das Skript manuell kopiert haben, sollten diese Hooks noch funktionieren, aber die Symlinks werden nicht mehr funktionieren. Wenn Sie das neue System verwenden, führen Sie rm .git/hooks/* aus, um die alten, nicht mehr benötigten Hooks zu entfernen.

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/*.

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
/**************************************************************************/
/*  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
/**************************************************************************/
/*  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 verwenden wir den Ruff-Linter und Code-Formatierer.

Ruff lokal verwenden

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

Installation

So wird ruff installiert:

pip3 install ruff --user

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

Manuelle Verwendung

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

ruff -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 vereinfachen, bieten wir Hooks für Git mit dem pre-commit-Python-Framework an, die ruff automatisch auf alle Ihre Commits mit der richtigen Version von ruff starten. Zum Einrichten:

pip install pre-commit
pre-commit install

Sie können den Hook auch manuell mit pre-commit run ausführen.

Bemerkung

Zuvor hatten wir einen Hook im Ordner misc/hooks bereitgestellt. Wenn Sie das Skript manuell kopiert haben, sollten diese Hooks noch funktionieren, aber die Symlinks werden nicht mehr funktionieren. Wenn Sie das neue System verwenden, führen Sie rm .git/hooks/* aus, um die alten, nicht mehr benötigten Hooks zu entfernen.

Editor-Integration

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

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.

  • You can use TODO:, FIXME:, NOTE:, WARNING:, or HACK: as admonitions when needed.

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() {
    // ...
}

For member variables, don't use Javadoc-style comments, but use single-line comments instead:

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;
};