whale-town-front/docs/代码注释规范.md

GDScript 代码注释规范

本文档详细说明了 whaleTown 项目中 GDScript 代码的注释规范，旨在提高代码可读性和维护性。

目录

• 基本原则
• 文件头注释
• 类和函数注释
• 变量注释
• 行内注释
• 特殊注释标记
• AI辅助注释指南

基本原则

注释的目的

• 解释为什么，而不是解释做什么
• 提供上下文，帮助理解代码意图
• 记录重要决策和设计考虑
• 警告潜在问题和注意事项

注释质量标准

• 简洁明了，避免冗余
• 使用中文，保持一致性
• 及时更新，与代码同步
• 避免显而易见的注释

文件头注释

每个 GDScript 文件都应该包含文件头注释，说明文件的用途和基本信息。

标准格式

# ============================================================================
# 文件名: PlayerController.gd
# 作用: 玩家角色控制器，处理玩家输入和移动逻辑
# 
# 主要功能:
# - 处理键盘和手柄输入
# - 控制角色移动和跳跃
# - 管理角色状态切换
# - 处理碰撞检测
#
# 依赖: MovementComponent, AnimationComponent
# 作者: [开发者名称]
# 创建时间: 2024-12-24
# ============================================================================

extends CharacterBody2D

管理器类文件头

# ============================================================================
# 游戏管理器 - GameManager.gd
# 
# 全局单例管理器，负责游戏状态管理和生命周期控制
# 
# 核心职责:
# - 游戏状态切换 (加载、认证、游戏中、暂停等)
# - 用户信息管理
# - 全局配置访问
# - 系统初始化和清理
#
# 使用方式:
#   GameManager.change_state(GameManager.GameState.IN_GAME)
#   GameManager.set_current_user("player123")
#
# 注意事项:
# - 作为自动加载单例，全局可访问
# - 状态变更会触发 game_state_changed 信号
# ============================================================================

extends Node

类和函数注释

类注释

# 玩家数据类
# 
# 存储和管理玩家的基本属性和状态信息
# 支持数据序列化和反序列化，用于存档系统
class_name PlayerData

# 武器组件类
# 
# 为角色提供武器功能，包括攻击、换弹、特殊技能等
# 可以挂载到任何具有攻击能力的角色上
#
# 使用示例:
#   var weapon = WeaponComponent.new()
#   weapon.setup_weapon("sword", 50)
#   add_child(weapon)
class_name WeaponComponent

函数注释格式

# 处理玩家输入并更新移动状态
# 
# 参数:
#   delta: float - 帧时间间隔
# 
# 返回值: 无
# 
# 注意事项:
# - 需要在 _physics_process 中调用
# - 会自动处理重力和碰撞
func handle_movement(delta: float) -> void:

# 验证用户输入的邮箱格式
# 
# 参数:
#   email: String - 待验证的邮箱地址
# 
# 返回值:
#   Dictionary - 包含验证结果和错误信息
#   {
#     "valid": bool,      # 是否有效
#     "message": String   # 错误信息（如果无效）
#   }
# 
# 使用示例:
#   var result = validate_email("test@example.com")
#   if result.valid:
#       print("邮箱格式正确")
static func validate_email(email: String) -> Dictionary:

变量注释

成员变量注释

# 玩家基础属性
@export var max_health: int = 100        # 最大生命值
@export var move_speed: float = 200.0    # 移动速度 (像素/秒)
@export var jump_force: float = -400.0   # 跳跃力度 (负值向上)

# 状态管理
var current_health: int                  # 当前生命值
var is_grounded: bool = false           # 是否在地面上
var can_double_jump: bool = true        # 是否可以二段跳

# 节点引用 - 在 _ready() 中初始化
@onready var sprite: Sprite2D = $Sprite2D
@onready var collision: CollisionShape2D = $CollisionShape2D
@onready var animation_player: AnimationPlayer = $AnimationPlayer

# 私有变量 - 内部使用
var _velocity: Vector2 = Vector2.ZERO    # 当前速度向量
var _last_direction: int = 1             # 最后面向方向 (1=右, -1=左)

常量注释

# 游戏配置常量
const GRAVITY: float = 980.0             # 重力加速度 (像素/秒²)
const MAX_FALL_SPEED: float = 1000.0     # 最大下落速度
const COYOTE_TIME: float = 0.1           # 土狼时间 (离开平台后仍可跳跃的时间)

# 输入动作名称
const ACTION_MOVE_LEFT: String = "move_left"
const ACTION_MOVE_RIGHT: String = "move_right"
const ACTION_JUMP: String = "jump"

# 动画名称常量
const ANIM_IDLE: String = "idle"
const ANIM_WALK: String = "walk"
const ANIM_JUMP: String = "jump"
const ANIM_FALL: String = "fall"

行内注释

复杂逻辑注释

func update_movement(delta: float):
    # 处理水平移动输入
    var input_direction = Input.get_axis("move_left", "move_right")
    
    if input_direction != 0:
        velocity.x = input_direction * move_speed
        _last_direction = sign(input_direction)  # 记录面向方向
    else:
        # 应用摩擦力，逐渐停止
        velocity.x = move_toward(velocity.x, 0, friction * delta)
    
    # 应用重力 (只在空中时)
    if not is_on_floor():
        velocity.y += gravity * delta
        velocity.y = min(velocity.y, max_fall_speed)  # 限制最大下落速度
    
    # 处理跳跃输入
    if Input.is_action_just_pressed("jump"):
        if is_on_floor():
            velocity.y = jump_force  # 普通跳跃
        elif can_double_jump:
            velocity.y = jump_force * 0.8  # 二段跳 (力度稍小)
            can_double_jump = false
    
    # 重置二段跳能力
    if is_on_floor() and not can_double_jump:
        can_double_jump = true

临时解决方案注释

func handle_collision(body: Node2D):
    # TODO: 重构碰撞处理逻辑，当前实现过于复杂
    # FIXME: 在某些情况下会出现重复碰撞检测
    # HACK: 临时解决方案，等待 Godot 4.6 修复相关 bug
    
    if body.has_method("take_damage"):
        # NOTE: 伤害计算需要考虑护甲和抗性
        var damage = calculate_damage(base_damage)
        body.take_damage(damage)

特殊注释标记

使用标准化的标记来标识不同类型的注释：

标记类型

# TODO: 待实现的功能
# TODO: 添加音效播放功能
# TODO: 实现存档系统

# FIXME: 需要修复的问题
# FIXME: 内存泄漏问题，需要及时释放资源
# FIXME: 在低帧率下移动不流畅

# HACK: 临时解决方案
# HACK: 绕过 Godot 引擎的已知 bug
# HACK: 临时方案，等待更好的实现

# NOTE: 重要说明
# NOTE: 此函数会修改全局状态，谨慎使用
# NOTE: 性能敏感代码，避免频繁调用

# WARNING: 警告信息
# WARNING: 不要在 _ready() 之前调用此函数
# WARNING: 此操作不可逆，请确认后执行

# OPTIMIZE: 性能优化点
# OPTIMIZE: 可以使用对象池优化内存分配
# OPTIMIZE: 考虑使用缓存提高查询效率

版本和兼容性标记

# @since 1.0.0 - 添加基础移动功能
# @deprecated 使用 new_movement_system() 替代
# @godot_version 4.5+ - 需要 Godot 4.5 或更高版本
# @platform_specific Windows/Linux - 仅在桌面平台可用

AI辅助注释指南

为AI提供的注释模板

当需要AI帮助补充注释时，请使用以下模板：

# [AI_COMMENT_REQUEST]
# 请为以下函数添加详细注释，包括：
# - 功能描述
# - 参数说明
# - 返回值说明
# - 使用示例
# - 注意事项
func complex_function(param1: String, param2: int) -> Dictionary:
    # 复杂的业务逻辑...
    pass

AI注释补充规则

1. 保持一致性 - 遵循项目现有的注释风格
2. 关注业务逻辑 - 重点解释业务含义，而非语法
3. 提供上下文 - 说明函数在整个系统中的作用
4. 标注复杂度 - 对复杂算法提供额外说明

示例：AI补充前后对比

补充前：

func calculate_damage(base_damage: int, armor: int, resistance: float) -> int:
    var final_damage = base_damage
    final_damage -= armor
    final_damage *= (1.0 - resistance)
    return max(1, final_damage)

AI补充后：

# 计算最终伤害值
# 
# 根据基础伤害、护甲值和抗性计算实际造成的伤害
# 伤害计算公式: (基础伤害 - 护甲) × (1 - 抗性)
# 
# 参数:
#   base_damage: int - 基础伤害值
#   armor: int - 目标护甲值 (减少固定伤害)
#   resistance: float - 目标抗性 (0.0-1.0, 减少百分比伤害)
# 
# 返回值:
#   int - 最终伤害值 (最小为1，确保至少造成1点伤害)
# 
# 使用示例:
#   var damage = calculate_damage(100, 20, 0.3)  # 结果: 56
# 
# 注意事项:
# - 护甲为负值时会增加伤害
# - 抗性超过1.0时可能导致负伤害，但会被限制为1
func calculate_damage(base_damage: int, armor: int, resistance: float) -> int:
    var final_damage = base_damage
    final_damage -= armor                    # 减去护甲值
    final_damage *= (1.0 - resistance)      # 应用抗性
    return max(1, final_damage)             # 确保最小伤害为1

注释最佳实践

什么时候需要注释

必须添加注释的情况：

• 复杂的算法和业务逻辑
• 非显而易见的设计决策
• 临时解决方案和已知问题
• 公共API和接口函数
• 性能敏感的代码段
• 平台特定或版本特定的代码

不需要注释的情况：

• 显而易见的代码 (var count = 0 # 计数器 ❌)
• 重复函数名的注释 (func get_name() -> String: # 获取名称 ❌)
• 过时或错误的注释

注释维护原则

# ✅ 好的注释 - 解释为什么这样做
# 使用二分查找提高大数组的查询效率
# 当数组长度超过100时，线性查找性能会显著下降
func binary_search(array: Array, target: Variant) -> int:

# ❌ 坏的注释 - 重复代码内容
# 遍历数组查找目标值
func linear_search(array: Array, target: Variant) -> int:

团队协作注释

# 多人协作时的注释规范
class_name NetworkManager

# @author: 张三 - 网络连接模块
# @author: 李四 - 数据同步模块
# @reviewer: 王五 - 代码审查
# @last_modified: 2024-12-24

# 网络连接状态枚举
# 
# 定义了客户端与服务器的连接状态
# 状态转换: DISCONNECTED -> CONNECTING -> CONNECTED -> DISCONNECTED
enum ConnectionState {
    DISCONNECTED,    # 未连接
    CONNECTING,      # 连接中
    CONNECTED,       # 已连接
    RECONNECTING     # 重连中 - @added by 李四 2024-12-20
}

注释检查清单

在提交代码前，请检查以下项目：

文件级别检查

• 文件头注释完整（文件名、作用、主要功能）
• 依赖关系说明清楚
• 作者和创建时间已填写

函数级别检查

• 公共函数有完整的参数和返回值说明
• 复杂函数有使用示例
• 特殊情况和注意事项已标注

代码级别检查

• 复杂逻辑有行内注释说明
• 魔法数字有常量定义和注释
• TODO/FIXME 标记有明确的处理计划

质量检查

• 注释内容准确，与代码一致
• 中文表达清晰，无错别字
• 注释格式符合项目规范

注释工具和插件

Godot编辑器设置

# 在 Godot 编辑器中设置注释快捷键
# 编辑器设置 -> 快捷键 -> 注释/取消注释: Ctrl+/

推荐的注释插件

• GDScript Language Server - 提供注释语法高亮
• Code Formatter - 自动格式化注释
• Documentation Generator - 自动生成API文档

---

总结

良好的注释是代码质量的重要组成部分。遵循本规范可以：

1. 提高代码可读性 - 帮助团队成员快速理解代码
2. 降低维护成本 - 减少后期修改和调试时间
3. 促进知识传承 - 保留设计思路和业务逻辑
4. 支持AI辅助开发 - 为AI提供更好的上下文信息

记住：好的注释解释为什么，而不是做什么。