60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
---
|
||
alwaysApply: true
|
||
---
|
||
# oops-framework & Cocos Creator 3.x 开发规范
|
||
|
||
- 引用其他文件函数时严格审核引用路径的正确性。
|
||
|
||
## 技术栈
|
||
|
||
- Cocos Creator 3.x + TypeScript 严格模式（优先 Interface/Type，杜绝 `any`）
|
||
- 全局对象 `oops` 访问框架功能，通过 `import { oops } from 'xxxx'` 获取
|
||
|
||
## 架构约束
|
||
|
||
- Model / View / System(Controller) 分层，禁止将所有逻辑塞入单个组件
|
||
- **禁止造轮子**：UI、资源、音频、事件、调度等基础功能必须使用 `oops.xxx` 内置模块
|
||
|
||
## 框架模块速查
|
||
|
||
| 模块 | 用途 | 关键 API |
|
||
|------|------|----------|
|
||
| `oops.gui` | UI 生命周期 | `open(name, data)` / `remove(name)`；频繁更新用 MVVM |
|
||
| `oops.res` | 资源加载/释放 | `load` / `loadAsync` / `release` |
|
||
| `oops.message` | 跨模块事件总线 | `on` / `off` / `dispatchEvent` |
|
||
| `oops.timer` | 定时任务 | `register`（禁止 `setInterval`） |
|
||
| ECS | 大量同类实体（弹幕、群怪） | 框架内置 ECS 库 |
|
||
| 行为树 | 复杂 NPC AI | `behavior-tree` 模块 |
|
||
| AsyncQueue | 按序异步初始化 | 规避回调地狱 |
|
||
|
||
### 严格禁止
|
||
|
||
- 用 `instantiate` + `addChild` 手动管理全屏 UI / 弹窗 → 必须走 `oops.gui`
|
||
- 组件间 `@property` 拖拽 / `find` 查找强引用 → 必须走 `oops.message` 事件解耦
|
||
- 所有 `oops.message.on` / `oops.timer.register` 必须在 `onDestroy` / `onDisable` 中注销
|
||
|
||
---
|
||
|
||
# 代码注释规范
|
||
|
||
## 核心原则
|
||
|
||
1. **Clean Code 优先**：命名糟糕则重构命名，而非堆注释
|
||
2. **Why > What**：注释解释"为什么"，禁止废话注释（如 `// 遍历数组`）
|
||
3. **JSDoc / TSDoc** 标准格式，注释使用中文，专业术语保留英文
|
||
4. **拒绝幽灵注释**：代码变更时必须同步更新注释，删除废弃注释；输出前自校注释与代码一致性
|
||
|
||
## 注释标准
|
||
|
||
- **文件头**：复杂/核心模块顶部用 `/** ... */` 简述职责
|
||
- **类/接口**：描述领域模型职责，标注关键生命周期或状态流转
|
||
- **公共方法**：必须 JSDoc，含功能简述、`@param`（含边界/可空说明）、`@returns`、可选 `@throws` / `@deprecated`
|
||
- **行内注释**：仅用于复杂正则、位运算、业务 Workaround；`//` 后留空格，放在代码正上方
|
||
- **标记标签**（大写）：`// TODO:` 未实现、`// FIXME:` 已知 Bug、`// HACK:` 妥协方案
|
||
|
||
## 输出要求
|
||
|
||
- 代码前指明使用了 oops-framework 哪个模块
|
||
- `oops` API 调用附带简明中文注释
|
||
- 检查所有监听是否在生命周期结束时注销
|