Up to date

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

Writing guidelines

Note spécifique à la traduction française * : Cette partie concerne la contribution que vous pouvez apporter à la documentation de Godot et contient, entre autre, des directives et le style à suivre. Cette partie est traduite en français mais gardez à l'esprit que le sujet est d'écrire de la documentation dans un anglais accessible. *Fin de la note.

En résumé, essayez de toujours :

1. Use the active voice

2. Utiliser des verbes d'action précis

3. Évitez les verbes qui se terminent par -ing

4. Supprimer les adverbes et adjectifs inutiles.

5. Interdire ces 8 mots : évident, simple, basique, facile, réel, juste, clair, cependant

6. L'utilisation de références explicites

7. L'utilisation de 's pour montrer la possession

8. Utilisez la virgule d'Oxford

Il existe 3 règles pour décrire les classes :

1. Donnez un aperçu du nœud dans la brève description

2. Mentionner quelles méthodes retournent un résulat si elles c'est utiles

3. Utilisez "si vrai" pour décrire les booléens

Note

Le travail d'un rédacteur technique consiste à regrouper le plus d'informations possible dans des phrases les plus petites et les plus claires possibles. Les présentes lignes directrices vous aideront à atteindre cet objectif.

Voir aussi

Consultez les directives relatives au contenu pour obtenir des informations sur les types de documentation que vous pouvez écrire dans la documentation officielle.

7 règles pour un anglais clair

Use the active voice

Use the active voice when possible. Take the classes, methods, and constants you describe as the subject. It's natural to write using the passive voice, but it's harder to read and produces longer sentences.

Passive :

The man **was bitten** by the dog.

Active :

The dog bit the man.

N'utilisez pas la voix passive :

void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.

Utilisez utilisez le nom du nœud comme nom :

void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.

Utiliser des verbes d'action précis

Privilégiez les verbes précis mais courants aux verbes génériques comme make, set, et toute expression que vous pouvez remplacer par un seul mot.

Ne répétez pas le nom de la méthode. Il indique déjà qu'il change la valeur pivot :

void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]

Expliquez quelle est la conséquence de ce "set" : utilisez des verbes précis comme place, position, rotate, fade, etc.

void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]

Évitez les verbes qui se terminent par -ing

Les formes progressives décrivent des actions continues. Par exemple, "is calling", "is moving".

N'utilisez pas la forme progressive pour des changements instantanés.

Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]

Utilisez présent simple, passé ou futur.

Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]

Exception : Si le sujet n'est pas clair, le remplacement des verbes "ing" n'est pas une amélioration. Par exemple, dans la phrase précédente, "it replaces" n'aurait pas beaucoup de sens là où "replacing" se trouve actuellement.

Vous pouvez utiliser le temps progressif pour décrire des actions qui sont continues dans le temps. Tout comme l'animation ou les coroutines.

Astuce

Les verbes peuvent se transformer en noms adjectifs avec -ing. Il ne s'agit pas d'une conjugaison, vous pouvez donc les utiliser : the remaining movement, the missing file, etc.

Supprimer les adverbes et adjectifs inutiles

Écrivez le moins d'adjectifs et d'adverbes possible. Ne les utilisez que s'ils ajoutent des informations clés à la description.

N'utilisez pas d'adverbes redondants ou dénués de sens. Des mots qui allongent la documentation mais n'ajoutent aucune information :

**Basically** a big texture [...]

Utilisez des phrases courtes dans un langage simple et descriptif :

A big texture [...]

Bannissez ces 8 mots

N'utilisez jamais ces 8 mots :

1. évident

2. simple

3. basique/ de base

4. facile

5. actuel

6. juste

7. clair/clairement

8. cependant (certains usages)

La création et la programmation de jeux n'est pas facile, et rien n'est facile pour quelqu'un qui apprend à utiliser l'API pour la première fois. D'autres mots de la liste, comme juste(just) ou actuel(actual) n'ajouteront aucune information à la phrase. N'utilisez pas non plus d'adverbes correspondants : évidemment, simplement, fondamentalement, facilement, en fait, clairement(obviously, simply, basically, easily, actually, clearly).

Ne pas faire exemple. Les mots interdits allongent la description et détournent l'attention des informations les plus importantes :

**TextureRect**
Control frame that **simply** draws an assigned texture. It can stretch or not. It's a **simple** way to **just** show an image in a UI.

Faire les supprimer :

**TextureRect**
[Control] node that displays a texture. The texture can stretch to the node's bounding box or stay in the center. Useful to display sprites in your UIs.

Le mot "simple" n'aide jamais. N'oubliez pas que pour les autres utilisateurs, tout peut être complexe ou les frustrer. Il n'y a rien de tel qu'un bon vieux c'est simple pour vous faire craquer. Voici l'ancienne brève description, la première phrase de la page du nœud Timer :

**Timer**
A **simple** Timer node.

** Expliquez** ce que fait le nœud à la place :

**Timer**
Calls a function of your choice after a certain duration.

N'utilisez pas "de base", c'est trop vague :

**Vector3**
Vector class, which performs **basic** 3D vector math operations.

Utilisez la brève description pour donner un aperçu du nœud :

**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.

L'utilisation de références explicites

Privilégier les références explicites aux références implicites.

N'utilisez pas d'expression comme "le premier", "le second", etc. Ils ne sont pas les plus courants en anglais, et ils vous obligent à vérifier la référence.

[code]w[/code] and [code]h[/code] define right and bottom margins. The **latter** two resize the texture so it fits in the defined margin.

Faire répéter des mots. Ils suppriment toute ambiguïté :

[code]w[/code] and [code]h[/code] define right and bottom margins. **[code]w[/code] and [code]h[/code]** resize the texture so it fits the margin.

Si vous devez répéter le même nom de variable 3 ou 4 fois, vous devez probablement reformuler votre description.

L'utilisation de 's pour montrer la possession

Évitez "The milk of the cow". En anglais, cela semble non-naturel. Écrivez plutôt "The cow's milk".

Ne pas faire écrire "of the X" :

The region **of the AtlasTexture that is** used.

Faire Utilisez les 's. Cela vous permet de mettre le sujet principal au début de la phrase, et de la garder courte :

The **AtlasTexture's** used region.

Utilisez la virgule d'Oxford pour énumérer quoi que ce soit

Tiré du dictionnaire Oxford :

La "virgule d'Oxford" est une virgule facultative qui précède le mot "et" à la fin d'une liste : Nous vendons des livres, des vidéos, et des magazines.

[...] Tous les écrivains et éditeurs ne l'utilisent pas, mais il peut clarifier le sens d'une phrase lorsque les éléments d'une liste ne sont pas des mots isolés : Ces éléments sont disponibles en noir et blanc, rouge et jaune, et bleu et vert.

Ne laissez pas le dernier élément d'une liste sans virgule :

Create a CharacterBody2D node, a CollisionShape2D node and a sprite node.

Ajoutez une virgule avant et ou ou, pour le dernier élément d'une liste comportant plus de deux éléments.

Create a CharacterBody2D node, a CollisionShape2D node, and a sprite node.

Comment rédiger des méthodes et des classes

Typage dynamique vs statique

Les exemples de code dans la documentation doivent suivre un style cohérent pour ne pas troubler les utilisateurs. Comme les indications de type statique sont une caractéristique optionnelle du GDScript, nous avons choisi de nous en tenir à l'écriture de code dynamique. Cela nous a permis d'écrire un GDScript concis et accessible.

Les sujets qui expliquent aux utilisateurs les concepts d'écriture de code statique font exception.

Ne pas faire ajouter une indication de type avec deux points ou par conversion :

const MainAttack := preload("res://fire_attack.gd")
var hit_points := 5
var name: String = "Bob"
var body_sprite := $Sprite2D as Sprite2D

Faire écrire des variables consistante avec le typage dynamique :

const MainAttack = preload("res://fire_attack.gd")
var hit_points = 5
var name = "Bob"
var body_sprite = $Sprite2D

Ne pas faire écrire de fonctions avec des arguments inférés ou des types de retour :

func choose(arguments: PackedStringArray) -> String:
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size := arguments.size()
    var choice: int = randi() % size
    return arguments[choice]

Faire écrire des fonctions en utilisant la frappe dynamique :

func choose(arguments):
    # Chooses one of the arguments from array with equal chances
    randomize()
    var size = arguments.size()
    var choice = randi() % size
    return arguments[choice]

Utiliser des exemples de codes du monde réel, quand c'est approprié

Les exemples du monde réel sont plus accessibles aux débutants que les foos et bars abstraits. Vous pouvez également les copier directement à partir de vos projets de jeu, en vous assurant que tout extrait de code se compile sans erreur.

Le fait d'écrire var speed = 10 plutôt que var my_var = 10 permet aux débutants de mieux comprendre le code. Il leur donne un cadre de référence pour utiliser les extraits de code dans un projet en direct.

N'écrivez pas d'exemples inventés :

@onready var a = preload("res://MyPath")
@onready var my_node = $MyNode


func foo():
    # Do stuff

Écrivez des exemples concrets :

@onready var sfx_player_gun = preload("res://Assets/Sound/SFXPlayerGun.ogg")
@onready var audio_player = $Audio/AudioStreamPlayer


func play_shooting_sound():
    audio_player.stream = sfx_player_gun
    audio_player.play()

Bien sûr, il y a des moments où il n'est pas pratique d'utiliser des exemples réels. Dans ces situations, vous devriez quand même éviter d'utiliser des noms tels que my_var, foo() ou my_func() et envisager des noms plus significatifs pour vos exemples.

Donnez un aperçu du nœud dans la brève description

La brève description est la phrase la plus importante de la référence. C'est le premier contact de l'utilisateur avec un nœud :

1. C'est la seule description dans le dialogue "Créer un nouveau nœud".

2. Il se trouve en haut de chaque page de la référence

La brève description doit expliquer le rôle du nœud et sa fonctionnalité, en 200 caractères maximum.

Ne faites pas de résumés petits et vagues :

**Node2D**
Base node for 2D system.

Donner un aperçu de la fonctionnalité du nœud :

**Node2D**
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.

Utilisez la description complète du nœud pour fournir plus d'informations, et un exemple de code, si possible.

Mentionner quelles méthodes retournent un résulat si elles c'est utiles

Certaines méthodes renvoient des valeurs importantes. Décrivez-les à la fin de la description, idéalement sur une nouvelle ligne. Il n'est pas nécessaire de mentionner les valeurs de retour pour toute méthode dont le nom commence par "set" ou "get".

N'utilisez pas la voix passive :

Vector2 move ( Vector2 rel_vec )
[...] The returned vector is how much movement was remaining before being stopped.

Toujours utilisez « Retourne ».

Vector2 move ( Vector2 rel_vec )
[...] Returns the remaining movement before the body was stopped.

Remarquez l'exception à la règle de la "voix directe" : avec la méthode de déplacement, un collisionneur externe peut influencer la méthode et le corps qui appelle move. Dans ce cas, vous pouvez utiliser la voix passive.

Utilisez "si vrai" pour décrire les booléens

Pour les variables membres booléennes, utilisez toujours si vrai et/ou si faux, pour rester explicite. Les contrôles si vrai ou si faux peuvent être ambigus et ne fonctionneront pas pour chaque variable membre.

De plus, entourez les valeurs booléennes, les noms de variables et les méthodes avec [code][/code].

Commencez par si vrai :

Timer.autostart
If [code]true[/code], the timer will automatically start when entering the scene tree.

Utiliser [code] autour des arguments

Dans la référence de classe, entourez toujours les arguments par [code][/code]. Dans la documentation et dans Godot, il s'affichera comme ceci. Lorsque vous éditez des fichiers XML dans le dépôt Godot, remplacez les arguments existants écrits comme 'ceci' ou `ceci` par [code]ceci[/code].

Vocabulaire commun à utiliser dans la documentation de Godot

Les développeurs ont choisi certains mots spécifiques pour désigner les zones de l'interface. Ils sont utilisés dans les sources, dans la documentation, et vous devriez toujours les utiliser au lieu de synonymes, afin que les utilisateurs sachent de quoi vous parlez.

Aperçu de l'interface et du vocabulaire commun

Dans le coin supérieur gauche de l'éditeur se trouvent les main menus. Au centre, les boutons changent le workspace. Et ensemble, les boutons en haut à droite sont les playtest buttons. La zone au centre, qui affiche l'espace 2D ou 3D, est le viewport. En haut, vous trouverez une liste de tools dans la toolbar.

Les onglets ou panneaux ancrables de chaque côté de la fenêtre de visualisation sont des docks. Vous avez le dock FileSystem dock, le Scene dock qui contient votre arbre de scènes, le Import dock, le Node dock et le Inspector ou Inspector dock. Avec la disposition par défaut, vous pouvez appeler les docks à onglets tabs : Scene tab, Node tab...

L'animation, le débogueur, etc. en bas de la fenêtre de visualisation (viewport) il y a des panels. Ensemble, ils forment les bottom panels.

Foldable areas of the Inspector are sections. The node's parent class names, which you can't fold, are Classes e.g. the CharacterBody2D class. And individual lines with key-value pairs are properties. E.g. position or modulate color are both properties.

Consignes relatives aux raccourcis clavier

Les raccourcis clavier et souris doivent utiliser la balise :kbd:, qui permet aux raccourcis de se démarquer du reste du texte et des ligne de code. Utilisez la forme compacte pour les touches de modification (Ctrl/Cmd) au lieu de leur forme orthographiée (Control/Command). Pour les combinaisons, utilisez le symbole + avec un espace de chaque côté du symbole.

Veillez à mentionner les raccourcis qui diffèrent sur macOS par rapport aux autres plateformes. Sur macOS, Cmd remplace souvent Ctrl dans les raccourcis clavier.

Essayez d'intégrer le raccourci dans les phrases du mieux que vous pouvez. Voici quelques exemples avec la balise :kbd: laissée telle quelle pour une meilleure visibilité :

• Appuyez sur :kbd:`Ctrl + Alt + T` pour basculer le panneau (:kbd:`Cmd + Alt + T` sur macOS).

• Appuyez sur :kbd:`Space` et maintenez le bouton gauche de la souris enfoncé pour se déplacer dans l'éditeur 2D.

• Appuyez sur :kbd:`Shift + Up Arrow` pour déplacer le nœud vers le haut de 8 pixels.