GDScript 编写风格指南

本编写风格指南列出了几条规定，能够让用户将 GDScript 代码编写得更加优雅。本指南旨在让用户编写更为整洁、可读的代码，促进项目、讨论和教程之间的一致性。本教程也希望能够因此鼓励开发者们能够开发出来代码自动格式化工具。

由于 GDScript 与 Python 非常接近，因此本指南的灵感来自 Python 的 PEP 8 编程风格指南。

风格指南并不是硬性的规则教条，有些情况下，你可能无法施行下面的一些规范。如果这种情况发生在你身上，最好自行进行选择，并询问其他开发人员的见解。

一般来说，在项目和团队中保持代码风格的一致性，比一板一眼地遵循本指南更为重要。

备注

Godot的内置脚本编辑器默认使用了很多这些规范，那么就让这内置脚本编辑器来帮助你吧。

下面是基于这些规范的完整的类的示例：

  1. class_name StateMachine
  2. extends Node
  3. ## Hierarchical State machine for the player.
  4. ##
  5. ## Initializes states and delegates engine callbacks ([method Node._physics_process],
  6. ## [method Node._unhandled_input]) to the state.
  9. signal state_changed(previous, new)
  11. @export var initial_state: Node
  12. var is_active = true:
  13.     set = set_is_active
  15. @onready var _state = initial_state:
  16.     set = set_state
  17. @onready var _state_name = _state.name
  20. func _init():
  21.     add_to_group("state_machine")
  24. func _enter_tree():
  25.     print("this happens before the ready method!")
  28. func _ready():
  29.     state_changed.connect(_on_state_changed)
  30.     _state.enter()
  33. func _unhandled_input(event):
  34.     _state.unhandled_input(event)
  37. func _physics_process(delta):
  38.     _state.physics_process(delta)
  41. func transition_to(target_state_path, msg={}):
  42.     if not has_node(target_state_path):
  43.         return
  45.     var target_state = get_node(target_state_path)
  46.     assert(target_state.is_composite == false)
  48.     _state.exit()
  49.     self._state = target_state
  50.     _state.enter(msg)
  51.     Events.player_state_changed.emit(_state.name)
  54. func set_is_active(value):
  55.     is_active = value
  56.     set_physics_process(value)
  57.     set_process_unhandled_input(value)
  58.     set_block_signals(not value)
  61. func set_state(value):
  62.     _state = value
  63.     _state_name = _state.name
  66. func _on_state_changed(previous, new):
  67.     print("state changed")
  68.     state_changed.emit()
  71. class State:
  72.     var foo = 0
  74.     func _init():
  75.         print("Hello!")

格式

编码与特殊字符

  • 使用换行符（LF）换行，而非 CRLF 或 CR。（编辑器默认）

  • 在每个文件的末尾使用一个换行符。（编辑器默认）

  • 使用不带字节顺序标记的 UTF-8 编码。（编辑器默认）

  • 使用制表符代替空格进行缩进。（编辑器默认）

缩进

每个缩进的缩进级别必须大于包含该缩进的代码块的缩进级别。

规范示例 :

  1. for i in range(10):
  2.     print("hello")

不规范示例 :

  1. for i in range(10):
  2.   print("hello")
  4. for i in range(10):
  5.         print("hello")

使用2个缩进级别来区分续行代码块与常规代码块。

规范示例 :

  1. effect.interpolate_property(sprite, "transform/scale",
  2.         sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
  3.         Tween.TRANS_QUAD, Tween.EASE_OUT)

不规范示例 :

  1. effect.interpolate_property(sprite, "transform/scale",
  2.     sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
  3.     Tween.TRANS_QUAD, Tween.EASE_OUT)

此规则的例外：数组、字典和枚举。使用单个缩进级别来区分续行代码块：

规范示例 :

  1. var party = [
  2.     "Godot",
  3.     "Godette",
  4.     "Steve",
  5. ]
  7. var character_dict = {
  8.     "Name": "Bob",
  9.     "Age": 27,
  10.     "Job": "Mechanic",
  11. }
  13. enum Tiles {
  14.     TILE_BRICK,
  15.     TILE_FLOOR,
  16.     TILE_SPIKE,
  17.     TILE_TELEPORT,
  18. }

不规范示例 :

  1. var party = [
  2.         "Godot",
  3.         "Godette",
  4.         "Steve",
  5. ]
  7. var character_dict = {
  8.         "Name": "Bob",
  9.         "Age": 27,
  10.         "Job": "Mechanic",
  11. }
  13. enum Tiles {
  14.         TILE_BRICK,
  15.         TILE_FLOOR,
  16.         TILE_SPIKE,
  17.         TILE_TELEPORT,
  18. }

行尾逗号

请在数组、字典和枚举的最后一行使用逗号，这样，在添加新元素时就不需要修改最后一行了，既能让版本控制中的重构更容易，也会让 Diff 也更美观。

规范示例 :

  1. enum Tiles {
  2.     TILE_BRICK,
  3.     TILE_FLOOR,
  4.     TILE_SPIKE,
  5.     TILE_TELEPORT,
  6. }

不规范示例 :

  1. enum Tiles {
  2.     TILE_BRICK,
  3.     TILE_FLOOR,
  4.     TILE_SPIKE,
  5.     TILE_TELEPORT
  6. }

单行列表中不需要行尾逗号，故在此情况下不要添加逗号。

规范示例 :

  1. enum Tiles {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT}

不规范示例 :

  1. enum Tiles {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT,}

空白行

用两个空行来包围函数和类定义：

  1. func heal(amount):
  2.     health += amount
  3.     health = min(health, max_health)
  4.     health_changed.emit(health)
  7. func take_damage(amount, effect=null):
  8.     health -= amount
  9.     health = max(0, health)
  10.     health_changed.emit(health)

函数内部使用一个空行来分隔每个逻辑片段。

备注

在类参考和本文档的短代码片段中，我们会在类和函数定义之间使用单个空行。

行的长度

把每行代码控制在100个字符以内。

如果可以的话，尽量把行控制在80个字符以下，既有助于在小屏幕上阅读代码，也有利于在外部文本编辑器中并排打开两个脚本。例如，在查看差异修订时。

一条语句一行

不要在同一行上合并多个语句。不要像 C 语言那样使用单行条件语句。

规范示例 :

  1. if position.x > width:
  2.     position.x = 0
  4. if flag:
  5.     print("flagged")

不规范示例 :

  1. if position.x > width: position.x = 0
  3. if flag: print("flagged")

该规则的唯一例外便是三元运算符：

  1. next_state = "idle" if is_on_floor() else "fall"

对多行语句进行排版以提高可读性

如果你的 if 语句特别长，亦或如果一条语句是嵌套的三元表达式，把它们拆分成多行可以提高可读性。由于这几行连续的代码仍属于同一个表达式，故应该缩进两级而非一级。

GDScript 允许使用括号或反斜杠将语句拆成多行，本指南倾向于使用括号，重构起来更简单。使用反斜杠的话，必须保证最后一行的末尾没有反斜杠；而如果是括号，则不必担心最后一行的反斜杠问题。

把条件表达式拆分成多行时，and 和 or 关键字应当放在下一行的开头，而非上一行的结尾。

规范示例 :

  1. var angle_degrees = 135
  2. var quadrant = (
  3.         "northeast" if angle_degrees <= 90
  4.         else "southeast" if angle_degrees <= 180
  5.         else "southwest" if angle_degrees <= 270
  6.         else "northwest"
  7. )
  9. var position = Vector2(250, 350)
  10. if (
  11.         position.x > 200 and position.x < 400
  12.         and position.y > 300 and position.y < 400
  13. ):
  14.     pass

不规范示例 :

  1. var angle_degrees = 135
  2. var quadrant = "northeast" if angle_degrees <= 90 else "southeast" if angle_degrees <= 180 else "southwest" if angle_degrees <= 270 else "northwest"
  4. var position = Vector2(250, 350)
  5. if position.x > 200 and position.x < 400 and position.y > 300 and position.y < 400:
  6.     pass

避免冗余的圆括号

避免在表达式和条件语句中使用括号，除非需要修改操作顺序或者将语句拆分多行编写，否则只会降低可读性。

规范示例 :

  1. if is_colliding():
  2.     queue_free()

不规范示例 :

  1. if (is_colliding()):
  2.     queue_free()

布尔运算

推荐使用英文布尔运算符，简单易懂：

  • 用 and 代替 &&。

  • 用 or 代替 ||。

  • 用 not 代替 !。

也可以在布尔运算符周围使用括号来消除歧义，这样还可以使长表达式更有可读性。

规范示例 :

  1. if (foo and bar) or not baz:
  2.     print("condition is true")

不规范示例 :

  1. if foo && bar || !baz:
  2.     print("condition is true")

注释间距

普通注释（ # ）与文档注释（ ## ）均应与注释正文保持一个空格的距离，而被注释掉的代码开头则不需要空格间隙。需要注意：代码区域注释（ #region / #endregion ）为保持其作用需要，不可以在井号后使用空格。

普通注释开头应该留一个空格，但如果是为了停用代码而将其注释掉则不需要留，以此区分文本注释和停用的代码。

规范示例 :

  1. # This is a comment.
  2. #print("This is disabled code")

不规范示例 :

  1. #This is a comment.
  2. # print("This is disabled code")

备注

在脚本编辑器中，要切换已注释的选定代码，请按 Ctrl + K。此功能会在选定行的开头添加一个 # 注释符号。

空格

时刻记得在运算符前后和逗号后使用一个空格。同时，请避免在字典引用和函数调用中使用多余的空格。

规范示例 :

  1. position.x = 5
  2. position.y = target_position.y + 10
  3. dict["key"] = 5
  4. my_array = [4, 5, 6]
  5. print("foo")

不规范示例 :

  1. position.x=5
  2. position.y = mpos.y+10
  3. dict ["key"] = 5
  4. myarray = [4,5,6]
  5. print ("foo")

不要用空格去垂直对齐表达式：

  1. x        = 100
  2. y        = 100
  3. velocity = 500

引号

尽量使用双引号，除非单引号可以让字符串中需要转义的字符变少。见如下示例：

  1. # Normal string.
  2. print("hello world")
  4. # Use double quotes as usual to avoid escapes.
  5. print("hello 'world'")
  7. # Use single quotes as an exception to the rule to avoid escapes.
  8. print('hello "world"')
  10. # Both quote styles would require 2 escapes; prefer double quotes if it's a tie.
  11. print("'hello' \"world\"")

数字

不要忽略浮点数中的前导和后缀零，否则会降低这些数字的可读性，很难一眼与整数区分开。

规范示例 :

  1. var float_number = 0.234
  2. var other_float_number = 13.0

不规范示例 :

  1. var float_number = .234
  2. var other_float_number = 13.

对于十六进制数字，请使用小写字母。小写字母较矮，使数字更易读。

规范示例 :

  1. var hex_number = 0xfb8c0b

不规范示例 :

  1. var hex_number = 0xFB8C0B

利用 GDScript 的文字下划线，让大数字更易读。

规范示例 :

  1. var large_number = 1_234_567_890
  2. var large_hex_number = 0xffff_f8f8_0000
  3. var large_bin_number = 0b1101_0010_1010
  4. # Numbers lower than 1000000 generally don't need separators.
  5. var small_number = 12345

不规范示例 :

  1. var large_number = 1234567890
  2. var large_hex_number = 0xfffff8f80000
  3. var large_bin_number = 0b110100101010
  4. # Numbers lower than 1000000 generally don't need separators.
  5. var small_number = 12_345

命名规定

这些命名规定遵循 Godot 引擎风格，不遵循这些规定都会使你的代码与内置的命名规定相冲突，导致风格不一致的代码.

文件命名

文件名用 snake_case （蛇形）命名法，对于具名类，将其名字从帕斯卡命名（大驼峰命名，PascalCase）转化为 snake_case 命名：

  1. # This file should be saved as `weapon.gd`.
  2. class_name Weapon
  3. extends Node
  1. # This file should be saved as `yaml_parser.gd`.
  2. class_name YAMLParser
  3. extends Object

这种命名与 Godot 源码中的 C++ 文件命名保持一致，也避免了由 Windows 导出到其他大小写敏感平台时所发生的问题。

类与节点

对类和节点名称使用帕斯卡命名法（大驼峰命名法，PascalCase）:

  1. extends CharacterBody3D

将类加载到常量或变量时也同样适用：

  1. const Weapon = preload("res://weapon.gd")

函数与变量

函数与变量使用 snake_case 命名：

  1. var particle_effect
  2. func load_level():

在用户必须覆盖的虚方法、私有函数、私有变量的名称前加一个下划线（_）：

  1. var _counter = 0
  2. func _recalculate_path():

信号

用过去时态（英文）来命名信号：

  1. signal door_opened
  2. signal score_changed

常量与枚举

使用 CONSTANT_CASE，全部大写，并用下划线（_）来分隔单词：

  1. const MAX_SPEED = 200

对枚举的名称使用 PascalCase，对其成员使用 CONSTANT_CASE， 因为这些成员是常量：

  1. enum Element {
  2.     EARTH,
  3.     WATER,
  4.     AIR,
  5.     FIRE,
  6. }

代码顺序

第一节主要讨论代码顺序。有关代码格式，请参见 格式。有关命名规定，请参见 命名规定。

我们建议按以下方式来组织 GDScript 代码：

  1. 01. @tool
  2. 02. class_name
  3. 03. extends
  4. 04. # docstring
  6. 05. signals
  7. 06. enums
  8. 07. constants
  9. 08. @export variables
  10. 09. public variables
  11. 10. private variables
  12. 11. @onready variables
  14. 12. optional built-in virtual _init method
  15. 13. optional built-in virtual _enter_tree() method
  16. 14. built-in virtual _ready method
  17. 15. remaining built-in virtual methods
  18. 16. public methods
  19. 17. private methods
  20. 18. subclasses

我们优化了代码顺序，从上往下阅读代码更加容易，帮助第一次阅读代码的开发人员了解代码的工作原理，同时避免与变量声明顺序相关的错误。

此代码顺序遵循四个经验法则：

  1. 先写信号和属性，然后再写方法。

  2. 先写公共成员，然后再写私有成员。

  3. 先写虚函数回调，然后再写类的接口。

  4. 先写对象的构造函数和初始化函数 _init 和 _ready ，然后再写修改对象的函数。

类声明

如果代码要在编辑器中运行，请将 @tool 注解写在脚本的第一行。

如有必要，在后面加上 class_name。你可以使用该特性将 GDScript 文件转换为项目中的全局类型。有关更多信息，请参阅 GDScript 参考。

然后，如果该类扩展了内置类型，请添加 extends 关键字。

接下来，你应该有该类的可选 文档注释。例如，你可以用它来向你的队友解释你的类的作用、它是如何工作的、以及其他开发人员应该如何使用它。

  1. class_name MyNode
  2. extends Node
  3. ## A brief description of the class's role and functionality.
  4. ##
  5. ## The description of the script, what it can do,
  6. ## and any further detail.

信号和属性

先声明信号，然后声明属性（即成员变量），这些都写在文档注释（docstring）之后。

在信号之后声明枚举，枚举可以用作其他属性的导出提示。

然后，按该顺序依次写入常量、导出变量、公共变量、私有变量和就绪加载（onready）变量。

  1. signal player_spawned(position)
  3. enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN}
  5. const MAX_LIVES = 3
  7. @export var job: Jobs = Jobs.KNIGHT
  8. @export var max_health = 50
  9. @export var attack = 5
  11. var health = max_health:
  12.     set(new_health):
  13.         health = new_health
  15. var _speed = 300.0
  17. @onready var sword = get_node("Sword")
  18. @onready var gun = get_node("Gun")

备注

GDScript编译器在 _ready 函数回调之前计算就绪加载（onready）变量，因此可以使用该虚函数来缓存节点依赖项，在你的类所依赖的场景中获取子节点。这便是上面的例子所展示的内容。

成员变量

如果变量只在方法中使用，请勿将该变量声明为成员变量，因为难以定位在何处使用了该变量。相反，你应该将这些变量在方法内部定义为局部变量。

局部变量

局部变量的声明位置离首次使用该局部变量的位置越近越好，让人更容易跟上代码的思路，而不需要上翻下找该变量的声明位置。

方法和静态函数

先声明类的属性，再声明类的方法。

从 _init() 回调方法开始，引擎将在内存创建对象时调用该方法，然后是 _ready() 回调，Godot 在向场景树添加一个节点时会调用该回调。

这些函数应声明在脚本最前面，以便显示该对象的初始化方式。

_unhandling_input() 和 _physics_process 等其他内置的虚回调则应该放在后面，控制对象的主循环和与游戏引擎的交互。

类的其余接口、公共和私有方法，均按照这个顺序呈现。

  1. func _init():
  2.     add_to_group("state_machine")
  5. func _ready():
  6.     state_changed.connect(_on_state_changed)
  7.     _state.enter()
  10. func _unhandled_input(event):
  11.     _state.unhandled_input(event)
  14. func transition_to(target_state_path, msg={}):
  15.     if not has_node(target_state_path):
  16.         return
  18.     var target_state = get_node(target_state_path)
  19.     assert(target_state.is_composite == false)
  21.     _state.exit()
  22.     self._state = target_state
  23.     _state.enter(msg)
  24.     Events.player_state_changed.emit(_state.name)
  27. func _on_state_changed(previous, new):
  28.     print("state changed")
  29.     state_changed.emit()

静态类型

从 Godot 3.1 开始，GDScript 支持 可选的静态类型。

声明类型

要声明变量的类型，请使用 <variable>: <type> ：

  1. var health: int = 0

要声明函数的返回类型，请使用 -> <type> ：

  1. func heal(amount: int) -> void:

推断类型

大部分情况下，你可以让编译器自行推断变量类型，用 := 来实现。在变量声明与变量类型写在同一行时使用该语法，除此之外还请显式指定变量类型。

规范示例 :

  1. var health: int = 0 # The type can be int or float, and thus should be stated explicitly.
  2. var direction := Vector3(1, 2, 3) # The type is clearly inferred as Vector3.

在类型不明确时指定类型，在类型提示多余时省略类型指定。

不规范示例 :

  1. var health := 0 # Typed as int, but it could be that float was intended.
  2. var direction: Vector3 = Vector3(1, 2, 3) # The type hint has redundant information.
  4. # What type is this? It's not immediately clear to the reader, so it's bad.
  5. var value := complex_function()

但在少数情况下，上下文缺失时，编译器会回退到函数的返回类型。例如，在节点的场景或文件被加载到内存中之前， get_node() 无法自动推断类型。在这种情况下，应明确指定类型。

规范示例 :

  1. @onready var health_bar: ProgressBar = get_node("UI/LifeBar")

也可以使用 as 关键字来转换返回类型，该类型会用于推导变量类型。

  1. @onready var health_bar := get_node("UI/LifeBar") as ProgressBar
  2. # health_bar will be typed as ProgressBar

这种做法也比第一种更加类型安全。

不规范示例 :

  1. # The compiler can't infer the exact type and will use Node
  2. # instead of ProgressBar.
  3. @onready var health_bar := get_node("UI/LifeBar")

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.