注释规范

通用要求

• 所有注释必须使用中文
• 注释必须清楚清晰，准确描述代码的用途和逻辑
• 避免无意义的注释（如 // 获取名称 在 getName() 上）

API 接口注释规范（Python FastAPI）

所有 FastAPI 接口必须遵守 OpenAPI 规范，使用标准的请求/响应格式定义。

详细规范见：OpenAPI 官方文档

Java 注释规范

每个类和每个方法都必须包含标准 JavaDoc 注释。

/**
 * 玩家传送管理器
 * <p>
 * 负责处理玩家的传送请求，包括跨世界传送和安全位置检测。
 * </p>
 *
 * @author 作者名
 * @since 1.0.0
 */
public class TeleportManager {

    /**
     * 将玩家传送到指定位置
     * <p>
     * 会先检测目标位置是否安全，如果不安全则寻找附近的安全位置。
     * </p>
     *
     * @param player 要传送的玩家，不能为 null
     * @param target 目标位置，包含世界、坐标和朝向
     * @param safe   是否启用安全检测，为 true 时会寻找安全落地点
     * @return 传送成功返回 true，玩家不在线或目标世界不存在时返回 false
     * @throws IllegalArgumentException 当 player 或 target 为 null 时抛出
     */
    public boolean teleport(Player player, Location target, boolean safe) {
        // 复杂逻辑需要行注释说明
        // 先检测目标区块是否已加载，避免传送时触发区块加载导致卡顿
        if (!target.getChunk().isLoaded()) {
            target.getChunk().load();
        }
        // ...
    }
}

Python 注释规范

每个类、每个方法/函数都必须包含标准 docstring 注释。

class QuestManager:
    """任务管理器
    
    负责任务的创建、进度追踪和奖励发放。
    支持主线任务、支线任务和日常任务三种类型。
    
    Attributes:
        quests: 当前所有活跃任务的字典，键为任务ID
        max_daily: 每日任务最大接取数量
    """
    
    def __init__(self, max_daily: int = 10):
        """初始化任务管理器
        
        Args:
            max_daily: 每日任务最大接取数量，默认为10
        """
        self.quests: dict[str, Quest] = {}
        self.max_daily = max_daily
    
    def accept_quest(self, player_id: str, quest_id: str) -> bool:
        """让玩家接取指定任务
        
        会检查任务是否存在、玩家是否满足接取条件、
        每日任务数量是否已达上限。
        
        Args:
            player_id: 玩家唯一标识符
            quest_id: 任务唯一标识符
            
        Returns:
            接取成功返回 True，条件不满足返回 False
            
        Raises:
            QuestNotFoundError: 当任务ID不存在时抛出
            PlayerOfflineError: 当玩家不在线时抛出
        """
        # 复杂逻辑需要行注释
        # 先检查每日任务限制，避免无谓的数据库查询
        if self._is_daily_limit_reached(player_id):
            return False
        # ...