Up to date

This page is up to date for Godot 4.3. 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

Il n'y a pas de directives écrites, mais le style de code convenu par les développeurs est appliqué via le metteur en forme de code clang-format, qui s'occupe pour vous de toutes nos conventions. Pour n'en citer que quelques-unes :

  • 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're 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

You need to use clang-format 17 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.

Crochet de pré commit

Pour faciliter l'utilisation, nous fournissons des hooks pour Git avec le framework Python`pre-commit <https ://pre-commit.com/>`__ qui exécutera automatiquement clang-format sur tous vos commits avec la version correcte de clang- format. Pour l'installation :

pip install pre-commit
pre-commit install

You can also run the hook manually with pre-commit run.

Note

Previously, we supplied a hook in the folder misc/hooks. If you copied the script manually, these hooks should still work, but symlinks will be broken. If you are using the new system, run rm .git/hooks/* to remove the old hooks that are no longer needed.

Installation

Voici comment installer clang-format :

  • Linux : la chaîne d'outils de clang est en généralement déjà empaquetée dans votre distribution. Si la version de votre distribution n'est pas celle requise, vous pouvez télécharger une version pré-compilée sur le site internet de LLVM, ou si votre distribution est basée sur Debian, utilisez les dépôts à jour.

  • macOS et Windows : Vous pouvez télécharger les binaires pré-compilées depuis le site web de LLVM. Vous devrez peut-être ajouter le chemin du répertoire des binaires à votre variable d'environnement PATH pour pouvoir appeler clang-format directement.

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

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.

For those, we use the Ruff linter and code formatter.

Using ruff locally

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

Installation

Here's how to install ruff:

pip3 install ruff --user

You then have different possibilities to apply ruff to your changes:

Utilisation manuelle

You can apply ruff manually to one or more files with the following command:

ruff -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 des hooks pour Git avec le framework Python`pre-commit <https ://pre-commit.com/>`__ qui exécutera ruff automatiquement sur tous vos commits avec la version correcte de « fraise ». Pour l'installation :

pip install pre-commit
pre-commit install

You can also run the hook manually with pre-commit run.

Note

Previously, we supplied a hook in the folder misc/hooks. If you copied the script manually, these hooks should still work, but symlinks will be broken. If you are using the new system, run rm .git/hooks/* to remove the old hooks that are no longer needed.

Intégration à l'éditeur

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

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