Richtlinien für den Codestil

Wenn Sie zum Quellcode von Godot beitragen, müssen Sie die unten aufgeführten Stil-Richtlinien befolgen. Einige von ihnen werden über den Prozess der kontinuierlichen Integration überprüft, und die Prüfer werden Sie auffordern, potenzielle Probleme zu beheben. Richten Sie Ihr System daher am besten wie unten beschrieben ein, um sicherzustellen, dass alle Ihre Commits den Richtlinien entsprechen.

C++ und Objective-C

Es gibt keine schriftlichen Richtlinien, aber der von den Entwicklern vereinbarte Code-Stil wird über das Clang-Format Code-Verschönerer durchgesetzt (Clang ist ein Compiler-Frontend), das für Sie alle unsere Konventionen berücksichtigt. Um nur einige zu nennen:

  • Einrückung und Ausrichtung sind beide Tabulatorbasiert (jeweils ein und zwei Tabulatoren)

  • Ein Leerzeichen um Mathe- und Zuweisungsoperatoren sowie nach Kommas

  • Zeiger- und Referenzoperatoren werden an die Variablenkennung 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 Quellbaum enthalten ist, aber nicht speziell für unser Projekt geschrieben wurde. Solcher Code stammt in der Regel von verschiedenen Upstream-Projekten mit ihren eigenen Styleguides (oder deren Fehlen), 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

These guidelines only cover code formatting. See C++ usage guidelines for a list of language features that are permitted in pull requests.

Lokale Verwendung des Clang-Formats

First of all, you will need to install clang-format. As of now, you need to use clang-format 13 to be compatible with Godot's format. Later versions might be suitable, but previous versions may not support all used options, or format some things differently, leading to style issues in pull requests.

Installation

So wird das Clang-Format installiert:

  • Linux: Normalerweise ist sie mit der clang-Toolchain, die von Ihrer Distribution gepackt wird, sofort verfügbar. Wenn Ihre Distro-Version nicht die erforderliche ist, können Sie eine vorkompilierte Version von der LLVM-Website herunterladen, oder wenn Sie ein Debian-Derivat verwenden, benutzen Sie die upstream repos.

  • macOS und Windows: Sie können vorkompilierte Binärdateien von der LLVM-Website <http://releases.llvm.org/download.html>`__ herunterladen. Möglicherweise müssen Sie den Pfad zum Ordner der Binärdatei zur Umgebungsvariablen ``PATH 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 eine oder mehrere Dateien manuell im Clang-Format 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 nur die fixierte Version 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 Baum 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 clang-format automatisch auf alle Ihre Commits anwendet, um sie zu prüfen, und Sie die Änderungen in den endgültigen Commit übernehmen lässt.

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 Verschönerungs-Plugins, die so konfiguriert werden können, dass das Clang-Format automatisch ausgeführt wird, beispielsweise jedes Mal, wenn Sie eine Datei speichern.

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

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

Header enthält

Beim Hinzufügen neuer C++ oder Objective-C Dateien oder beim Einfügen neuer Header in vorhandene, 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. Stellen Sie sicher, dass Sie den Dateinamen anpassen.

  • 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 Wurzelverzeichnis eingebunden werden. Diese Includes sollten mit Anführungszeichen erfolgen, 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) 2007-2021 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2021 Godot Engine contributors (cf. AUTHORS.md).   */
/*                                                                       */
/* 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) 2007-2021 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2021 Godot Engine contributors (cf. AUTHORS.md).   */
/*                                                                       */
/* 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 Styleguide 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 Quellbaum enthaltene Skripte verwenden ebenfalls Python.

Für diese folgen wir dem Black Stil-Richtlinien. Schwärzen Sie Ihre Python-Änderungen mit Black.

Black lokal verwenden

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

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 Sie können die Änderungen beim endgültigen Commit bestätigen.

Dieser "Hook" ist ein Skript, das unter diverses/Hooks zu finden ist. Die Installationsanweisungen finden Sie unter README.md in diesem Ordner.

Editor Integration

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

Stil-Richtlinien

Dieser Kommentarstil-Leitfaden gilt für alle Programmiersprachen, die innerhalb der Codebasis von Godot verwendet werden.

  • Beginnen Sie Kommentare mit einem Leerzeichen, um sie von deaktiviertem Code zu unterscheiden.

  • Verwenden Sie für Kommentare die Groß- und Kleinschreibung. Beginnen Sie Kommentare mit einem Großbuchstaben und beenden Sie sie immer mit einem Punkt.

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

  • Brechen Sie Kommentare auf ~100 Zeichen um.

  • Sie können TODO:, FIXME:, NOTE:, oder HACK: als Benennungen verwenden, wenn dies erforderlich 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 nicht dem Skripting ausgesetzt sind. Dies liegt daran, dass diese Methoden stattdessen in der 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;
};