Hua.Todo/.trae/rules/commenting.md

alwaysApply, description

alwaysApply	description
true	强制项目注释规范（C# / TypeScript）：新增或修改代码必须补全必要注释，便于维护与跨平台开发。

注释规范（必须遵守）

通用

• 新增或修改的代码必须包含足够注释，使“不了解该模块的人”也能理解其职责、边界与关键决策。
• 优先使用 XML 文档注释（///），而不是随意的行内注释。
• 不允许无意义注释（例如“初始化变量”“进入方法”）。注释必须解释“为什么/约束/边界/副作用”。
• 不允许出现“TODO/FIXME”但无上下文或无处理方案的注释。

C#（.NET / MAUI）

• 所有 public / protected 的 类、接口、方法、属性 必须提供 XML 文档注释，至少包含：
  • summary：一句话说明用途
  • 对关键参数/返回值：param / returns
  • 对异常或副作用：在 summary 中明确说明（例如会注册系统钩子/会启动后台服务）
• 对 跨平台逻辑：
  • 禁止在同一文件内混写多个平台的大段 #if 实现；应优先使用 partial、接口与平台目录分离。
  • 平台分离后的公共入口处必须说明“平台差异在哪里、默认实现是什么、为什么这么做”。
• 对 异步/后台任务：
  • 必须说明启动时机、错误处理策略、是否需要 UI 线程、以及是否可并发/可重入。
• 对 安全/隐私：
  • 禁止在日志或注释中输出密钥、Token、用户隐私信息。

TypeScript / Vue（前端）

• 对导出的函数/类型必须有注释，解释用途与输入输出。
• 对“与后端/MAUI 交互”的协议字段（例如全局变量、事件名）必须注释说明来源与约束。