kev/Drawer/AI/docs/coding_rules.md

# 编码风格约束（微软风格，强制）

以下规则便于 AI 与人工修改代码时一致、可静态检查。

## 1. 花括号（必须）

- **if / else / for / foreach / while / do / using / lock / fixed**：一律使用花括号，禁止单行无括号写法。
- **正确**：`if (x) { Do(); }`  
- **错误**：`if (x) Do();` 或 `if (x) return;`（单行也不省略括号）

## 2. 命名

- **PascalCase**：类型、方法、属性、公共字段、常量、枚举成员、命名空间
- **camelCase**：局部变量、参数、私有字段（私有字段可加 `_` 前缀）
- **接口**：`I` 前缀（如 `IFormRegistry`）
- **异步方法**：后缀 `Async`（如 `AskAsync`；同步方法如 GetHistoryForLlm 不加 Async）

## 3. 类型与可空性

- 启用 **Nullable 上下文**。引用类型需明确可空（`string?`、`ChatSession?`）；不可空则不加 `?`。
- 避免无谓的 `!`；仅在确知非 null 时使用。

## 4. 行与格式

- 单行不宜过长；复杂表达式或参数列表可换行缩进对齐。
- **else if** 写成独立块并加括号。
- **switch**：每个 case 用 `break` 或 `return` 明确结束；需要 fall-through 时显式写注释。

## 5. 异步与取消

- 异步方法返回 `Task` 或 `Task<T>`，命名带 `Async`。
- 长时间运行或可能取消的操作应接受 `CancellationToken`（通常为最后一参，默认 `default`）。

## 6. 注释与文档

- 公共 API（接口、公开方法/属性）使用 `///` 摘要；复杂逻辑可加简短行内注释。
- 不写无信息量的注释（如重复方法名）。

## 7. 其他

- **var**：类型明显时可用；否则写显式类型以提高可读性。
- **using**：实现 `IDisposable` 的实例优先用 `using` 或 `await using`。
- **集合**：对外暴露只读集合时用 `IReadOnlyList<T>`、`IReadOnlyDictionary<K,V>` 等，避免直接暴露可变集合。