【杂谈】Godot 信号命名规范

学博而后可约，事历而后知要。

一、信号命名规范

1. 过去时态描述事件

   # ✅ 正确
   signal health_changed      # 状态已改变
   signal item_collected      # 物品已收集
   signal enemy_died          # 敌人已死亡

   # ❌ 避免
   signal change_health       # 动词原形
   signal collecting_item     # 进行时态

2. 明确作用对象

   # ✅ 层级清晰
   signal player_jumped
   signal boss_phase_changed

   # ✅ 通用事件
   signal inventory_updated   # 无明确主语但领域明确

3. 参数命名清晰

   # ✅ 类型注释 + 自解释参数
   signal weapon_switched(old_weapon: Weapon, new_weapon: Weapon)

   # ❌ 模糊参数
   signal data_updated(value)  # 无类型提示

---

二、信号处理函数规范

1. 命名格式

   func _on_[发送节点名]_[信号名]():
       pass

   # 示例
   func _on_player_health_changed(old_val, new_val):
       pass

   func _on_button_pressed():
       pass

2. 处理函数位置
   • 集中管理：在接收信号的节点脚本中定义
   • 禁止操作：不要在被销毁的节点中处理信号

3. 参数匹配

   # 信号定义
   signal quest_completed(quest_id: String, xp_reward: int)

   # ✅ 处理函数
   func _on_quest_system_quest_completed(q_id: String, xp: int):
       pass

   # ❌ 参数不匹配
   func _on_quest_system_quest_completed():  # 缺少参数
       pass

---

三、信号连接规范

1. 连接方式优先级

   # 方式1：编辑器可视化连接 (检查器->节点->信号)
   # 适合静态关系明确的节点

   # 方式2：代码动态连接
   # 适合运行时创建的节点
   $Player.health_changed.connect(_on_player_health_changed)

2. 推荐连接时机

   func _ready():
       # 在父节点初始化时连接
       $Button.pressed.connect(_on_button_pressed)

3. 高级连接参数

   # 一次性连接
   enemy.died.connect(_on_enemy_died, CONNECT_ONE_SHOT)

   # 带绑定参数
   button.pressed.connect(_on_button_pressed.bind(button_index))

---

四、参数类型规范

1. 强类型声明 (Godot 4+)

   # ✅ 明确参数类型
   signal level_loaded(map_data: Dictionary, difficulty: int)

   # ❌ 不推荐松散类型
   signal level_loaded(map_data, difficulty)

2. 复杂对象传递

   # 传递资源引用
   signal item_obtained(item: InventoryItem)

   # 传递场景坐标
   signal projectile_fired(start_pos: Vector2, target_pos: Vector2)

---

五、错误处理规范

1. 安全检查

   # 连接前检查节点有效性
   if is_instance_valid(target_node):
       target_node.signal.connect(handler)

   # 检查是否已连接
   if not player.health_changed.is_connected(_on_health_changed):
       player.health_changed.connect(_on_health_changed)

2. 解连接规范

   func _exit_tree():
       # 节点销毁时主动断开连接
       if health_changed.is_connected(_on_health_changed):
           health_changed.disconnect(_on_health_changed)

---

六、代码组织建议

1. 信号集中管理

   # 使用全局脚本统一管理(event_bus.gd)
   signal player_spawned
   signal game_paused
   signal game_resumed

   # 任何地方均可访问
   EventBus.player_spawned.emit()

2. 文档注释

   ## 当玩家完成跳跃动作时触发
   ## @param jump_height: float - 跳跃高度(像素)
   signal player_jumped(jump_height: float)

---

总结准则：

1. 清晰性 > 简洁性：名称要自解释
2. 强类型：Godot 4+ 必须使用类型提示
3. 命名一致性：全项目保持相同风格
4. 解耦思维：通过信号实现节点间松耦合

遵循这些规范可以显著提升代码可维护性。