代码文件顶部注释规范

所有代码文件必须在文件顶部包含功能描述注释。

⚠️ 核心强制要求

注释内容（按优先级）

• 核心功能概述（必需）：第一句话说明文件是干什么的

• 主要接口/功能（必需）：列出主要函数/类

• 快速开始示例（推荐）：最简单的使用示例

禁止事项

• ❌ 详细描述架构分层

• ❌ 重复代码中已明确的信息

• ❌ 冗长的执行流程描述

篇幅控制

• 单个文件注释 ≤ 30 行

AI Agent 行为要求

创建新文件时

• 必须自动添加符合规范的顶部注释

• 优先描述功能，少描述架构

修改现有文件时

• 缺少注释则添加

• 注释过于复杂则精简

• 确保注释与实际代码一致

参考资料

• references/comment-templates.md

• 各语言注释模板详细说明

• references/best-practices.md

• 注释最佳实践