godotengine/godot-contributing-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-contributing-docs.git synced 2026-02-25 02:34:39 +03:00
Code Issues Packages Projects Releases Wiki Activity

Migrate guidelines for GDScript language design from godot docs.

Browse Source
This commit is contained in:
Lukas Tenbrink
2026-01-18 10:14:29 +01:00
parent 65ba300d95
commit 71b43d6a2a
2 changed files with 61 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
engine/guidelines/gdscript_language_guidelines.rst Normal file
View File

@@ -0,0 +1,60 @@
GDScript language design guidelines
===================================
Annotation guidelines
---------------------
In Godot 3 we had a lot of keywords (including ``tool``, ``export``, ``onready``).
This had the following disadvantages:
- Overcomplication of the language grammar.
- Possible conflicts with user identifiers.
- Need to touch the parser in a major way to add a new keyword.
So in Godot 4 we introduced the concept of annotations. An annotation is a modifier
(an attribute, a marker) that can be applied to an entire script, a declaration,
a statement, or a location in the source code. Annotations can optionally take
additional arguments, listed in parentheses. Annotation arguments must be constant
expressions or string literals (in a few special cases where the argument value
must be resolved in the parser rather than in the analyzer).
Currently, an annotation target can be a combination of the following
``GDScriptParser::AnnotationInfo::TargetKind`` flags:
+-----------------+----------------------------------------------+-----------------------------+
| **Target Kind** | **Description** | **Example** |
+=================+==============================================+=============================+
| ``SCRIPT`` | The entire script. | ``@tool`` |
+-----------------+----------------------------------------------+-----------------------------+
| ``CLASS`` | A class (both the outermost and inner ones). | ``@abstract`` |
+-----------------+----------------------------------------------+-----------------------------+
| | ``VARIABLE`` | Other types of class members. | ``@export`` |
| | ``CONSTANT`` | | |
| | ``SIGNAL`` | | |
| | ``FUNCTION`` | | |
+-----------------+----------------------------------------------+-----------------------------+
| ``STATEMENT`` | Statements inside a function. | ``@warning_ignore`` |
+-----------------+----------------------------------------------+-----------------------------+
| ``STANDALONE`` | Some place inside a class or a line | | ``@export_category`` |
| | in the source code. | | ``@warning_ignore_start`` |
| | | |
| | 1. Class pseudo-members. | |
| | 2. Markers for the start and end | |
| | of a warning-ignoring region. | |
+-----------------+----------------------------------------------+-----------------------------+
**When to use a keyword and when an annotation to implement a new feature?**
- **General rule:** Do not use keywords unless they are required by the language grammar
and the parser. Do not use annotations for independent syntactic units.
- Use keywords for class member declarators (``var``, ``const``, ``func``).
- Use annotations for class member modifiers (``@export``, ``@onready``, ``@abstract``).
- Use keywords for operators within expressions (``and``), for delimiters in statements
(``in``, ``when``), and declarations (``extends``).
.. note::
For historical reasons, some existing annotations and keywords do not strictly
follow these guidelines. Choosing between implementing a feature as an annotation
or as a language keyword is a nuanced decision that should be made through discussion
with other GDScript developers.

1
engine/guidelines/index.rst
View File

@@ -14,6 +14,7 @@ This section explains guidelines for contributing to the engine.
cpp_usage_guidelines
code_style
editor_style_guide
gdscript_language_guidelines
.. _doc_handling_compatibility_breakages: