NewQuant/.kilocode/rules/naming_conventions.md

# 命名约定规则 (Naming Conventions)

本项目定义了一套统一的命名约定，以确保代码库的一致性和可读性。

## 1. 文件命名规范

### 1.1 Python 文件
- 使用 **小写字母 + 下划线**：`backtest_engine.py`, `data_manager.py`
- 避免使用连字符或空格
- 测试文件以 `test_` 前缀开头：`test_backtest_engine.py`

### 1.2 配置文件
- 使用小写字母和下划线：`config.json`, `strategy_params.yaml`
- 环境配置文件使用 `.env` 或 `.env.{environment}` 格式

### 1.3 数据文件
- 遵循 `{数据类型}_{日期范围}.{扩展名}` 格式
- 示例：`btc_ohlcv_2023_2024.csv`, `strategy_results_202401.json`

## 2. 变量命名规范

### 2.1 普通变量
- 使用 **小写字母 + 下划线**（snake_case）
- 使用描述性名称，避免缩写
- ✅ 正确示例：`current_price`, `trade_volume`, `stop_loss_price`
- ❌ 错误示例：`cp`, `tv`, `sl`

### 2.2 布尔变量
- 使用 `is_`, `has_`, `are_` 等前缀
- ✅ 正确示例：`is_valid`, `has_position`, `are_orders_filled`
- ❌ 错误示例：`valid`, `position`, `filled`

### 2.3 私有变量
- 使用单下划线前缀（约定俗成的私有）
- ✅ 正确示例：`_internal_cache`, `_last_order_id`
- ❌ 错误示例：`__private_var`（除非确实需要 name mangling）

### 2.4 临时变量
- 循环变量可使用单字母或简短名称
- ✅ 正确示例：`for i in range(n):`, `for bar in bars:`

## 3. 常量命名规范

### 3.1 全局常量
- 使用 **全大写字母 + 下划线**（SCREAMING_SNAKE_CASE）
- 定义在文件顶部或单独的 `constants.py` 模块中
- ✅ 正确示例：`MAX_POSITION = 5`, `DEFAULT_COMMISSION_RATE = 0.0003`
- ❌ 错误示例：`max_position`, `default_commission_rate`

### 3.2 配置常量
- 使用全大写字母和下划线
- ✅ 正确示例：`SYMBOL_FUTURES_SUFFIX = ".FG"`

## 4. 函数命名规范

### 4.1 普通函数
- 使用 **小写字母 + 下划线**（snake_case）
- 函数名应清晰表达其功能
- ✅ 正确示例：`calculate_metrics()`, `get_bar_history()`, `send_order()`
- ❌ 错误示例：`calc()`, `getData()`, `send()`

### 4.2 返回布尔值的函数
- 使用 `is_`, `has_`, `are_` 等前缀
- ✅ 正确示例：`is_trending_up()`, `has_active_orders()`, `are_positions_valid()`

### 4.3 私有函数
- 使用单下划线前缀
- ✅ 正确示例：`_validate_params()`, `_calculate_pnl()`

## 5. 类命名规范

### 5.1 公共类
- 使用 **大驼峰命名法**（PascalCase）
- ✅ 正确示例：`BacktestEngine`, `SimpleLimitBuyStrategy`, `DataManager`
- ❌ 错误示例：`backtest_engine`, `simple_limit_buy_strategy`

### 5.2 抽象基类
- 使用 `ABC` 后缀或 `Base` 前缀
- ✅ 正确示例：`Strategy(ABC)`, `BaseIndicator`

### 5.3 异常类
- 使用 `Error` 或 `Exception` 后缀
- ✅ 正确示例：`BacktestError`, `OrderExecutionException`

## 6. 特定领域命名规范

### 6.1 交易相关
- 方向：`BUY`, `SELL`, `CLOSE_LONG`, `CLOSE_SHORT`
- 订单类型：`LIMIT`, `MARKET`, `STOP`
- 持仓：`LONG`, `SHORT`, `FLAT`

### 6.2 策略参数
- 使用描述性名称，包含参数含义
- ✅ 正确示例：`stop_loss_points`, `take_profit_points`, `range_factor`
- ❌ 错误示例：`sl`, `tp`, `rf`

### 6.3 K线数据
- 时间周期：`1m`, `5m`, `15m`, `1h`, `4h`, `1d`
- OHLCV：`open`, `high`, `low`, `close`, `volume`

## 7. 数据库/缓存命名规范

### 7.1 缓存键
- 使用冒号分隔的层次结构
- ✅ 正确示例：`strategy:rb:positions`, `market:btc:price`

### 7.2 日志文件
- 使用 `{策略名}/{品种}.log` 格式
- ✅ 正确示例：`logs/SpectralTrendStrategy/rb.log`

## 8. 命名一致性检查清单

在提交代码前，请确认以下检查项：

- [ ] 所有变量名使用 snake_case
- [ ] 所有类名使用 PascalCase
- [ ] 所有常量使用 SCREAMING_SNAKE_CASE
- [ ] 函数名清晰表达功能
- [ ] 命名具有描述性，避免模糊缩写
- [ ] 私有成员使用下划线前缀
- [ ] 布尔变量使用适当的前缀

## 9. 命名反模式（应避免）

- ❌ 使用单个字母 `l`, `O`, `I` 作为变量名（容易与数字 1, 0 混淆）
- ❌ 使用魔法数字或字符串（应定义为常量）
- ❌ 使用不一致的命名风格混合
- ❌ 使用过于通用的名称如 `data`, `info`, `temp`
- ❌ 使用项目保留名称如 `strategy`, `engine`, `manager`