# Coding Style (Experiment Phase)

本文件是 `research-proposal` 阶段的最小可用代码规范。目标不是“写得漂亮”，而是：
- 让实验可复现、可审查、可扩展
- 让结果与结论能被证据指针（日志/表格/图表）支撑

## 1) 结构与规模

- 单文件建议 ≤400 行；超过就拆分模块。
- 模块化优先：数据、模型、训练、评估、可视化、工具分离。
- 配置集中管理：使用不可变配置对象（如 `@dataclass(frozen=True)` 或等价方案）。

## 2) 可复现性优先

- 所有随机性来源必须可控（seed、采样、数据打乱）。
- 所有关键超参必须来自配置文件/配置对象，禁止散落在代码里。
- 所有运行命令必须能复制粘贴复跑（记录到报告或日志中）。

## 3) 日志与错误处理

- 使用 logger，不使用 `print`（除非是最小 PoC 且明确说明）。
- 记录：
  - 配置（完整 dump）
  - 关键指标（每个 epoch/step）
  - 数据/模型版本信息（可选但推荐）
- 错误处理：
  - 捕获具体异常并给出可行动的提示
  - 失败也要写进实验报告（禁止只保留成功记录）

## 4) 类型与文档

- 所有公共函数/入口函数写类型标注（或等价注解）。
- 关键模块有简短 docstring：输入/输出/副作用/假设。
- 任何“看起来像结果”的常数，都必须能追溯到日志/表格/图表，不要写死在代码里当结论。

## 5) 测试与最小校验

实验代码也要有最低限度的校验：
- 数据加载/预处理：shape、范围、缺失值处理（sanity check）
- 训练循环：能在极小样本上跑通（smoke test）
- 评估指标：输入输出与边界条件正确（unit test）

## 6) Definition of Done（最小交付）

完成一次“可写进报告的实验”至少满足：
- [ ] 可复跑命令 + 配置文件/配置对象齐全
- [ ] 结果产物路径明确（logs/、checkpoints/、metrics.json 等）
- [ ] 至少 1 个 sanity check（见 `experiment-reproducibility.md`）
- [ ] 报告中每个关键数字都能指向证据指针（文件路径/表/图）