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.
..highlight:: none
Passive:
::
The man **was bitten** by the dog.
Active:
::
The dog bit the man.
**Don't** use the passive voice:
::
void edit_set_pivot ( Vector2 pivot )
[...] This method **is implemented** only in some nodes that inherit Node2D.
**Do** use the node's name as a noun:
::
void edit_set_pivot ( Vector2 pivot )
[...] Only some Node2Ds **implement** this method.
Use precise action verbs
~~~~~~~~~~~~~~~~~~~~~~~~
Favor precise yet common verbs over generic ones like ``make``, ``set``,
and any expression you can replace with a single word.
**Don't** repeat the method's name. It already states it sets the pivot
value to a new one:
::
void edit_set_pivot ( Vector2 pivot )
Set the pivot position of the 2D node to [code]pivot[/code] value. [...]
**Do** explain what's the consequence of this "set": use precise verbs
like ``place``, ``position``, ``rotate``, ``fade``, etc.
::
void edit_set_pivot ( Vector2 pivot )
Position the node's pivot to the [code]pivot[/code] value. [...]
Avoid verbs that end in -ing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The progressive forms describe continuous actions. E.g. "is calling",
"is moving".
**Don't** use the progressive form for instant changes.
::
Vector2 move ( Vector2 rel_vec )
Move the body in the given direction, **stopping** if there is an obstacle. [...]
**Do** use simple present, past, or future.
::
Vector2 move ( Vector2 rel_vec )
Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]
Exception: If the subject is not clear, replacing "ing" verbs is not an
improvement. For example, in the previous sentence, "it replaces"
would not make much sense where "replacing" currently is.
You may use the progressive tense to describe actions that are
continuous in time. Anything like animation or coroutines.
..tip::
Verbs can turn into adjectival nouns with -ing. This is not a
conjugation, so you may use them: ``the remaining movement``,
``the missing file``, etc.
Remove unnecessary adverbs and adjectives
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Write as few adjectives and adverbs as possible. Only use them if they
add key information to the description.
**Don't** use redundant or meaningless adverbs. Words that lengthen the
documentation but don't add any information:
::
**Basically** a big texture [...]
**Do** write short sentences in a simple, descriptive language:
::
A big texture [...]
Ban these 8 words
~~~~~~~~~~~~~~~~~
**Don't** ever use these 8 banned words:
1. obvious
2. simple
3. basic
4. easy
5. actual
6. just
7. clear
8. however (some uses)
Game creation and programming aren't simple, and nothing's easy to
someone learning to use the API for the first time. Other words in the
list, like ``just`` or ``actual`` won't add any info to the sentence.
Don't use corresponding adverbs either: obviously, simply, basically,
easily, actually, clearly.
**Don't** example. The banned words lengthen the description and take
attention away from the most important info:
::
**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.
**Do** remove them:
::
**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.
"Simple" never helps. Remember, for other users, anything could be
complex or frustrate them. There's nothing like a good old *it's simple*
to make you cringe. Here's the old brief description, the first sentence
on the Timer node's page:
::
**Timer**
A **simple** Timer node.
**Do** explain what the node does instead:
::
**Timer**
Calls a function of your choice after a certain duration.
**Don't** use "basic", it is too vague:
::
**Vector3**
Vector class, which performs **basic** 3D vector math operations.
**Do** use the brief description to offer an overview of the node:
::
**Vector3**
Provides essential math functions to manipulate 3D vectors: cross product, normalize, rotate, etc.
Use explicit references
~~~~~~~~~~~~~~~~~~~~~~~
Favor explicit references over implicit ones.
**Don't** use words like "the former", "the latter", etc. They're not
the most common in English, and they require you to check the reference.
::
[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.
**Do** repeat words. They remove all ambiguity:
::
[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.
If you need to repeat the same variable name 3 or 4 times, you probably
need to rephrase your description.
Use 's to show possession
~~~~~~~~~~~~~~~~~~~~~~~~~
Avoid "The milk **of** the cow". It feels unnatural in English. Write "The cow's
milk" instead.
**Don't** write "of the X":
::
The region **of the AtlasTexture that is** used.
**Do** use ``'s``. It lets you put the main subject at the start of the
sentence, and keep it short:
::
The **AtlasTexture's** used region.
Use the Oxford comma to enumerate anything
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
From the Oxford dictionary:
The 'Oxford comma' is an optional comma before the word 'and' at the end of a list:
*We sell books, videos, and magazines.*
[...] Not all writers and publishers use it, but it can clarify the meaning of a sentence when the items in a list are not single words:
*These items are available in black and white, red and yellow, and blue and green.*
**Don't** leave the last element of a list without a comma:
::
Create a KinematicBody2D node, a CollisionShape2D node and a sprite node.
**Do** add a comma before `and` or `or`, for the last
element of a list with more than two elements.
::
Create a KinematicBody2D node, a CollisionShape2D node, and a sprite node.
How to write methods and classes
--------------------------------
Dynamic vs static typing
~~~~~~~~~~~~~~~~~~~~~~~~
The code examples in the documentation should follow a consistent style not to
confuse users. As static type hints are an optional feature of GDScript, we
chose to stick to writing dynamic code. This leads to writing GDScript that is
concise and accessible.
The exception is topics that explain static typing concepts to users.
**Don't** add a type hint with a colon or by casting:
