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.

Tant que vous veillez à ce que votre style corresponde au code environnant et que vous n'introduisez pas d'espaces de fin de ligne ou d'indentation basée sur des espaces, tout devrait bien se passer. Toutefois, si vous avez l'intention de participer régulièrement, nous vous conseillons vivement de configurer clang-format localement pour vérifier et corriger automatiquement tous vos commits.

Avertissement

Le style de code de Godot ne doit pas être appliqué à du code tiers, c'est-à-dire qui est inclus dans l'arbre des sources de Godot mais qui n'a pas été écrit spécifiquement pour notre projet. Un tel code provient généralement de différents projets en amont avec leurs propres guides de style (ou leur absence), et ne veut pas introduire de différences qui rendraient la synchronisation avec les dépôts en amont plus difficile.

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.

Utiliser clang-format localement

Tout d'abord, vous devrez installer clang-format. Pour le moment, vous devez utiliser clang-format 8.x pour être compatible avec le format de Godot. Les versions ultérieures pourraient convenir, mais les versions précédentes comportaient des bugs qui entraîneront des modifications dans le formatage du code actuel.

Installation

Voici comment installer clang-format :

  • Linux : Il sera généralement disponible prêt à l'emploi avec la chaîne d'outils de clang empaquetée par 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 web de la LLVM, ou si vous êtes sur un dérivé de Debian, utilisez les dépôts upstream.
  • 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 depuis n'importe quel endroit.

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

Utilisation manuelle

Vous pouvez appliquer manuellement clang-format à un ou plusieurs fichiers avec la commande suivante :

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.

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

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

La plupart des IDE ou des éditeurs de code disposent de plugins d'embellissement qui peuvent être configurés pour exécuter automatiquement clang, par exemple chaque fois que vous enregistrez un fichier.

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

(Les PR pour étendre cette liste avec des plugins testés sont les bienvenues.)

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) 2007-2020 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2020 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-2020 Juan Linietsky, Ariel Manzur.                 */
/* Copyright (c) 2014-2020 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

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 ces derniers, nous suivons le guide de style PEP-8, qui n'est cependant pas aussi fortement appliqué que pour le code C++. Si vous le souhaitez, vous pouvez vérifier et formater vos modifications Python en utilisant autopep8.