Up to date

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

Lignes directrices pour le style du code

Lorsque vous contribuez au code source de Godot, vous devez suivre les directives de style décrites ci-dessous. Certaines d'entre elles sont vérifiées par le biais du processus d'intégration continue et les examinateurs vous demanderont de résoudre les problèmes potentiels. Il est donc préférable de configurer votre système comme indiqué ci-dessous pour vous assurer que tous vos commits respectent les directives.

C++ et Objective-C

There are no written guidelines, but the code style agreed upon by the developers is enforced via the clang-format code beautifier, which takes care for you of all our conventions. To name a few:

  • L'indentation et l'alignement sont tous les deux basés sur des tabulations (respectivement une et deux tabulations)

  • Un espace autour des opérateurs mathématiques et d'affectation, ainsi qu'après les virgules

  • Les opérateurs de pointeurs et de références sont attachés à l'identifiant de la variable, pas au nom du type

  • Voir plus loin concernant les inclusions en en-tête

Les règles utilisées par clang-format sont décrites dans le fichier .clang-format du dépôt de Godot.

As long as you ensure that your style matches the surrounding code and that you not introducing trailing whitespace or space-based indentation, you should be fine. If you plan to contribute regularly, however, we strongly advise that you set up clang-format locally to check and automatically fix all your commits.

Avertissement

Godot's code style should not be applied to third-party code, i.e. 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.

Le code tiers est généralement inclus dans le dossier thirdparty/ et peut donc être facilement exclu des scripts de formatage. Dans les rares cas où un extrait de code tiers doit être inclus directement dans un fichier Godot, vous pouvez utiliser /* clang-format off */ et /* clang-format on */ pour indiquer au "clang-format" d'ignorer une partie du code.

Voir aussi

Ces directives ne couvrent que le formatage du code. Voir Directives d'utilisation du C++ pour une liste des caractéristiques du langage qui sont autorisées dans les pull requests.

Utiliser clang-format localement

Tout d'abord, vous devez installer clang-format. À partir de maintenant, vous devez utiliser clang-format 13 pour être compatible avec le format de Godot's. Les versions ultérieures peuvent convenir, mais les versions précédentes peuvent ne pas supporter toutes les options utilisées, ou formater certaines choses différemment, ce qui entraîne des problèmes de style dans les pull requests.

Installation

Voici comment installer clang-format :

  • Linux: It will usually be available out-of-the-box with the clang toolchain packaged by your distribution. If your distro version is not the required one, you can download a pre-compiled version from the LLVM website, or if you are on a Debian derivative, use the upstream repos.

  • macOS and Windows: You can download precompiled binaries from the LLVM website. You may need to add the path to the binary's folder to your system's PATH environment variable to be able to call clang-format out of the box.

Vous avez alors différentes possibilités pour appliquer le clang-format à vos modifications :

Utilisation manuelle

You can apply clang-format manually for one or more files with the following command:

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

  • -i signifie que les modifications doivent être écrites directement dans le fichier (par défaut, clang-format n'affichera la version corrigée que dans le terminal).

  • Le chemin peut pointer vers plusieurs fichiers, soit l'un après l'autre, soit en utilisant des * comme dans un shell Unix typique. Faites attention lors de l'utilisation des * afin de ne pas utiliser le format clang sur des objets compilés (fichiers .o et .a) qui se trouvent dans l'arbre de Godot. Il vaut donc mieux utiliser core/*.{cpp,h} que core/*.

Crochet de pré commit

Pour faciliter l'utilisation, nous fournissons un crochet de pré-commission pour Git qui s'exécutera automatiquement au format clang sur tous vos commits pour les vérifier, et vous permettra d'appliquer ses changements dans le commit final.

This "hook" is a script that can be found in misc/hooks, refer to that folder's README.md for installation instructions.

Si le format de votre clang n'est pas dans le PATH, vous devrez peut-être modifier le pre-commit-clang-format pour qu'il pointe vers le binaire correct et qu'il fonctionne. Le crochet a été testé sous Linux et macOS, mais devrait également fonctionner dans le Git Shell sous Windows.

Plugin IDE

Most IDEs or code editors have beautifier plugins that can be configured to run clang-format automatically, for example, each time you save a file.

Voici une liste non exhaustive de plugins d'embellissement pour quelques IDE :

(Pull requests are welcome to extend this list with tested plugins.)

L'en-tête comprend

Lors de l'ajout de nouveaux fichiers C++ ou Objective-C ou de l'inclusion de nouveaux en-têtes dans des fichiers existants, les règles suivantes doivent être suivies :

  • Les premières lignes du fichier doivent être l'en-tête de copyright de Godot et la licence du MIT, copiées-collées à partir d'un autre fichier. Veillez à ajuster le nom du fichier.

  • Dans un en-tête .h, les gardes d'inclusion doivent être utilisés sur ce modèle : FILENAME_H.

  • Dans un fichier .cpp (par exemple filename.cpp), le premier include doit être celui où la classe est déclarée (par exemple #include "filename.h"), suivi d'une ligne vide pour la séparation.

  • Puis viennent les en-têtes de la base de code de Godot, inclus dans l'ordre alphabétique (imposé par le clang-format) avec les chemins relatifs au dossier racine. Ces inclusions doivent être faites avec des guillemets, par exemple #inclure "core/object.h". Le bloc des includes de l'en-tête Godot doit alors être suivi d'une ligne vide pour la séparation.

  • Enfin, les en-têtes tiers (provenant soit de thirdparty soit des chemins d'inclusion du système) viennent ensuite et doivent être inclus avec les symboles < et >, par exemple #include <png.h>. Le bloc des en-têtes tiers doit également être suivi d'une ligne vide pour la séparation.

  • Les en-têtes Godot et tiers doivent être inclus dans le fichier qui les requiert, c'est-à-dire dans l'en-tête .h si utilisé dans le code déclaratif ou dans le .cpp si utilisé uniquement dans le code impératif.

Exemple :

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

Le code Java de Godot (principalement en platform/android) est également mis en forme par clang-format, donc voir les instructions ci-dessus pour le régler. Gardez à l'esprit que ce guide de style ne s'applique qu'au code écrit et maintenu par Godot, et non au code d'une tierce partie comme le sous-dossier java/src/com/google.

Python

Le système de construction SCons de Godot est écrit en Python, et divers scripts inclus dans l'arbre des sources utilisent également Python.

Pour ceux-là, nous suivons le Guide du style Black. Noircissez vos changements Python en utilisant Black.

Utiliser black localement

First of all, you will need to install Black. Black requires Python 3.7+ to run.

Installation

Voici comment installer black :

pip3 install black --user

Vous avez alors différentes possibilités pour appliquer black à vos modifications :

Utilisation manuelle

Vous pouvez appliquer manuellement black à un ou plusieurs fichiers avec la commande suivante :

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

  • -l 120 signifie que le nombre de caractères autorisés par ligne est de 120. Ce nombre a été convenu par les développeurs.

  • Le chemin peut pointer vers plusieurs fichiers, soit l'un après l'autre, soit en utilisant des wildcards comme dans un shell Unix typique.

Crochet de pré commit

Pour faciliter l'utilisation, nous fournissons un pre-commit hook pour Git qui exécutera automatiquement black sur tous vos commits pour les vérifier, et vous permettra d'appliquer ses changements dans le commit final.

Ce "hook" est un script qui peut être trouvé dans misc/hooks, reportez-vous au README.md de ce dossier pour les instructions d'installation.

Intégration à l'éditeur

Many IDEs or code editors have beautifier plugins that can be configured to run black automatically, for example, each time you save a file. For details, you can check Black editor integration.

Guide de style pour les commentaires

Ce guide de style de commentaires s'applique à tous les langages de programmation utilisés dans la base de code de Godot.

  • Commencez les commentaires par un caractère espace pour les distinguer du code désactivé.

  • Utilisez la casse pour les commentaires. Commencez vos commentaires par une majuscule et terminez-les toujours par un point.

  • Référencez les noms et les valeurs des variables/fonctions en utilisant des backticks.

  • Limitez les commentaires à ~100 caractères.

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

Exemple :

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

Ne répétez pas ce que dit le code dans un commentaire. Expliquez le pourquoi plutôt que comment.

Mauvais :

// Draw loading screen.
draw_load_screen();

Vous pouvez utiliser des commentaires de style Javadoc au-dessus des définitions de fonctions ou de macros. Il est recommandé d'utiliser les commentaires de style Javadoc seulement pour les méthodes qui ne sont pas exposées aux scripts. En effet, les méthodes exposées doivent être documentées dans la référence XML class à la place.

Exemple :

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

Pour les variables membres, n'utilisez pas de commentaires de type Javadoc mais plutôt des commentaires d'une seule ligne :

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