Linee guida sullo stile del codice

When contributing to Godot's source code, you will be expected to follow the style guidelines outlined below. Some of them are checked via the Continuous Integration process and reviewers will ask you to fix potential issues, so best setup your system as outlined below to ensure all your commits follow the guidelines.

C++ e Objective-C

Non ci sono linee guida scritte, ma lo stile del codice concordato dagli sviluppatori è applicato tramite l'abbellitore di codice clang-format, che si occupa di tutte le nostre convenzioni. Per citarne alcune:

L'indentazione e l'allineamento sono entrambi basati su tabulazioni (rispettivamente una e due tabulazioni)
Uno spazio attorno agli operatori matematici e di assegnazione, nonché dopo le virgole
Gli operatori di puntatore e di riferimento sono attaccati all'identificatore della variabile, non al nome del tipo
See further down regarding header includes

Le regole utilizzate da clang-format sono descritte nel file .clang-format del repository di Godot.

Finché ci si assicura che il proprio stile corrisponda al codice circostante e che non si introducano spazi vuoti finali o indentazioni basate su spazi, non ci dovrebbero essere problemi. Se si prevede di contribuire regolarmente, tuttavia, consigliamo vivamente di impostare clang-format localmente per controllare e correggere automaticamente tutti i propri commit.

Avvertimento

Lo stile del codice di Godot non dovrebbe essere applicato al codice di terze parti, ovvero al codice incluso nel codice sorgente di Godot, ma non scritto specificamente per il nostro progetto. Tale codice proviene solitamente da diversi progetti upstream con le proprie guide di stile (o la loro assenza) e non vogliamo introdurre differenze che renderebbero più difficile sincronizzare i repository upstream.

Third-party code is usually included in the thirdparty/ folder and can thus easily be excluded from formatting scripts. For the rare cases where a third-party code snippet needs to be included directly within a Godot file, you can use /* clang-format off */ and /* clang-format on */ to tell clang-format to ignore a chunk of code.

Vedi anche

Queste linee guida trattano solo la formattazione del codice. Consultare C++ usage guidelines per un elenco di funzionalità del linguaggio consentite nelle pull request.

Utilizzare clang-format localmente

È necessario utilizzare clang-format 17 per essere compatibili con il formato di Godot. Versioni successive potrebbero essere adatte, ma quelle precedenti potrebbero non supportare tutte le opzioni utilizzate o formattare alcune cose in modo diverso, causando problemi di stile nelle pull request.

Hook di pre-commit

Per semplicità d'uso, forniamo degli hook per Git con il framework pre-commit di Python che eseguirà automaticamente clang-format su tutti i proprio commit con la versione corretta di clang-format. Per configurarlo:

pip install pre-commit
pre-commit install

È anche possibile eseguire manualmente l'hook tramite il comando pre-commit run.

Nota

In precedenza, fornivamo un hook nella cartella misc/hooks. Se lo script è stato copiato manualmente, questi hook dovrebbero continuare a funzionare, ma i collegamenti simbolici non funzioneranno. Se si sta utilizzando il nuovo sistema, eseguire rm .git/hooks/* per rimuovere i vecchi hook che non sono più necessari.

Installazione

Ecco come installare 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.

Sono quindi disponibili diverse possibilità per applicare clang-format alle proprie modifiche:

Utilizzo manuale

È possibile applicare clang-format manualmente per uno o più file con il seguente comando:

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

-i means that the changes should be written directly to the file (by default clang-format would only output the fixed version to the terminal).
The path can point to several files, either one after the other or using wildcards like in a typical Unix shell. Be careful when globbing so that you don't run clang-format on compiled objects (.o and .a files) that are in Godot's tree. So better use core/*.{cpp,h} than core/*.

Estensione per IDE

La maggior parte degli IDE o degli editor di codice includono estensioni di abbellimento che si possono configurare per eseguire clang-format automaticamente, ad esempio, ogni volta che si salva un file.

Ecco una lista non esaustiva di estensioni di abbellimento per alcuni IDE:

Qt Creator: Plugin Beautifier
Visual Studio Code: Clang-Format
Visual Studio: Clang Power Tools 2022
vim: vim-clang-format
CLion: A partire dalla versione 2019.1, non è richiesto alcuna estensione. Abilita invece ClangFormat

(Sono benvenute pull request per ampliare questa lista con estensioni testate.)

Header includes

When adding new C++ or Objective-C files or including new headers in existing ones, the following rules should be followed:

Le prime righe del file dovrebbero contenere l'intestazione del copyright di Godot e la licenza MIT, copiate e incollate da un altro file. Assicurarsi di cambiare il nome del file.
In a .h header, include guards should be used with the form FILENAME_H.
In a .cpp file (e.g. filename.cpp), the first include should be the one where the class is declared (e.g. #include "filename.h"), followed by an empty line for separation.
Seguono le intestazioni provenienti dal codice di Godot, incluse in ordine alfabetico (imposto da clang-format) con percorsi relativi alla cartella radice. Queste inclusioni si dovrebbero definire tra virgolette, ad esempio #include "core/object.h". Il blocco dell'intestazione di Godot dovrebbe quindi essere seguito da una riga vuota per la separazione.
Finally, third-party headers (either from thirdparty or from the system's include paths) come next and should be included with the < and > symbols, e.g. #include <png.h>. The block of third-party headers should also be followed by an empty line for separation.
Godot and third-party headers should be included in the file that requires them, i.e. in the .h header if used in the declarative code or in the .cpp if used only in the imperative code.

Esempio:

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

Anche il codice Java di Godot (principalmente in platform/android) è applicato tramite clang-format, quindi consulta le istruzioni precedenti per configurarlo. Si noti che questa guida di stile si applica solo al codice scritto e gestito da Godot, non a codice di terze parti come la sottocartella java/src/com/google.

Python

Il sistema di compilazione SCons di Godot è scritto in Python e anche vari script inclusi nell'albero sorgente utilizzano Python.

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

Utilizzo di ruff localmente

Prima di tutto, sarà necessario installare Ruff. Ruff richiede Python 3.7+ per funzionare.

Installazione

Ecco come installare ruff:

pip3 install ruff --user

Ci sono quindi diverse possibilità per applicare ruff alle proprie modifiche:

Utilizzo manuale

È possibile applicare manualmente ruff a uno o più file con il seguente comando:

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

-l 120 significa che il numero consentito di caratteri per riga è 120. Questo numero è stato concordato dagli sviluppatori.
Il percorso può puntare a più file, uno dopo l'altro oppure utilizzando caratteri jolly come in una tipica shell Unix.

Hook di pre-commit

Per semplicità d'uso, forniamo degli hook per Git con il framework pre-commit <https://pre-commit.com/>`__ in Python che eseguirà ``ruff automaticamente su tutti i propri commit con la versione corretta di ruff. Per configurarlo:

pip install pre-commit
pre-commit install

È anche possibile eseguire manualmente l'hook tramite il comando pre-commit run.

Nota

In precedenza, fornivamo un hook nella cartella misc/hooks. Se lo script è stato copiato manualmente, questi hook dovrebbero continuare a funzionare, ma i collegamenti simbolici non funzioneranno. Se si sta utilizzando il nuovo sistema, eseguire rm .git/hooks/* per rimuovere i vecchi hook che non sono più necessari.

Integrazione all'editor

Molti IDE o editor di codice dispongono di estensioni di abbellimento che si possono configurare per eseguire automaticamente ruff, ad esempio ogni volta che si salva un file. Per più dettagli, consultare Ruff Integrations.

Guida di stile per i commenti

Questa guida di stile per i commenti si applica a tutti i linguaggi di programmazione utilizzati nel codice base di Godot.

Cominciare i commenti con uno spazio per distinguerli dal codice disabilitato.
Usate la maiuscola iniziale per i commenti (sentence case). Cominciare i commenti con una lettera maiuscola e concluderli sempre con un punto.
Fare riferimento a nomi e a valori di variabili o funzioni utilizzando gli apici inversi (backtick).
Limita i commenti a circa 100 caratteri.
È concesso utilizzare TODO:, FIXME:, NOTE:, WARNING: o HACK: come ammonimenti dove necessario.

Esempio

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

Non ripetere ciò che dice il codice in un commento. Spiega il perché piuttosto che il come.

Male:

// Draw loading screen.
draw_load_screen();

È concesso utilizzare commenti in stile Javadoc sopra le definizioni di funzioni o macro. Si consiglia di utilizzare commenti in stile Javadoc soltanto per i metodi non esposti allo scripting. Questo perché i metodi esposti si dovrebbero documentare nei file XML del riferimento classi.

Esempio

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

Per le variabili membro, non utilizzare commenti in stile Javadoc, ma utilizzare invece commenti su una sola riga:

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