# 命名约定规则

本项目定义了统一的命名规范，确保代码可读性和一致性。

## 文件命名

### Python 源文件

- 使用 **小写字母** 和 **下划线** (`snake_case`)
- 模块名应简洁明了
- 避免使用缩写

```python
# 推荐
factor_processor.py
data_process.py
utils.py

# 不推荐
factorproc.py
dataProcess.py
Util.py
```

### 目录命名

- 使用 **小写字母** 和 **下划线**
- 含义明确的目录名

```
# 推荐
main/factor/
main/utils/
main/data/update/

# 不推荐
main/Factor/
main/Utils/
main/data/Update/
```

### 配置文件

- 使用小写下划线命名
- 后缀明确（如 `.env`, `.yml`, `.yaml`）

```
.env
.gitignore
requirements.txt
```

## 变量命名

### 普通变量

- 使用 **小写下划线** (`snake_case`)
- 名称应表达变量的含义
- 避免无意义的单字母（循环变量除外）

```python
# 推荐
stock_code = "600519"
close_prices = df["close"]
rolling_mean = grouped["close"].rolling(window=5).mean()

# 不推荐
s = "600519"
c = df["close"]
rm = grouped["close"].rolling(window=5).mean()
```

### 常量

- 使用 **全大写** 和 **下划线** (`UPPER_SNAKE_CASE`)
- 定义在模块顶部或单独的常量文件

```python
# 推荐
WINDOW_SIZE = 20
EPSILON = 1e-8
DEFAULT_JOIN = "left"

# 不推荐
windowSize = 20
epsilon = 1e-8
default_join = "left"
```

### 临时变量

- 使用 **单下划线前缀** 表示临时变量
- 或使用有意义的临时变量名

```python
# 推荐
df["_temp_calc"] = df["close"] * 1.1
result = [x for x in _ if x > 0]

# 不推荐
df["temp"] = df["close"] * 1.1
result = [x for x in a if x > 0]
```

### 私有变量

- 使用 **双下划线前缀**（Python 名称修饰）
- 或单下划线前缀（约定私有）

```python
class FactorCalculator:
    def __init__(self):
        self._default_window = 20  # 约定私有
        self.__internal_cache = {}  # 名称修饰（更严格）
```

## 函数命名

### 公共函数

- 使用 **小写下划线** (`snake_case`)
- 动词开头，表达函数行为

```python
# 推荐
def get_rolling_factor(df):
    pass

def calculate_moving_average(prices, window):
    pass

def merge_with_industry_data(df, industry_df):
    pass

# 不推荐
def rollingFactor(df):  # 违反 snake_case
    pass

def Factor(df):  # 不清晰
    pass
```

### 私有函数

- 使用 **单下划线前缀**

```python
def _internal_calculation(df):
    """内部计算函数，不对外暴露"""
    pass
```

### 数据处理函数

```python
# 推荐：明确表达输入输出
def read_and_merge_h5_data(h5_filename, key, columns, df=None, join="left"):
    pass

def load_factor_data(factor_type):
    pass

def save_predictions(predictions, output_path):
    pass
```

## 类命名

- 使用 **大驼峰命名** (`PascalCase`)
- 名词或名词短语

```python
# 推荐
class FactorCalculator:
    pass

class DataProcessor:
    pass

class StockAnalyzer:
    pass

# 不推荐
class factorCalculator:  # 违反 PascalCase
    pass

class data_processor:  # 违反 PascalCase
    pass
```

## DataFrame 列命名

### 因子列

- 使用 **小写下划线**
- 清晰表达因子含义
- 分类变量使用 `cat_` 前缀

```python
# 推荐：因子
df["volume_change_rate"]  # 成交量变化率
df["flow_lg_elg_intensity"]  # 主力资金流强度
df["chip_concentration_range"]  # 筹码集中度范围

# 推荐：分类变量
df["cat_is_positive"]  # 是否正收益（0/1）
df["cat_volume_breakout"]  # 成交量突破信号
df["cat_winner_price_zone"]  # 获利盘价格区域
```

### 中间计算列

- 使用 **单下划线前缀** 表示临时列

```python
# 推荐
df["_is_positive"] = (df["pct_chg"] > 0).astype(int)
df["_pos_returns"] = df["pct_chg"].where(df["pct_chg"] > 0, 0)

# 不推荐
df["temp_positive"] = (df["pct_chg"] > 0).astype(int)
df["posRet"] = df["pct_chg"].where(df["pct_chg"] > 0, 0)
```

### 排名列

- 使用 `rank_` 前缀

```python
df["rank_act_factor1"] = df.groupby("trade_date")["act_factor1"].rank(ascending=False, pct=True)
```

### 通用后缀

| 后缀 | 含义 | 示例 |
|------|------|------|
| `_change` | 变化量 | `cost_support_15pct_change` |
| `_ratio` | 比值 | `flow_divergence_ratio` |
| `_accel` | 加速度 | `flow_lg_elg_accel` |
| `_spike` | 异常值 | `vol_spike` |
| `_std` | 标准差 | `vol_std_5` |
| `_ma` | 移动平均 | `maobv_6` |
| `_return` | 收益率 | `future_return` |
| `_volatility` | 波动率 | `volatility` |

## 股票相关术语缩写

| 缩写 | 全称 | 示例列名 |
|------|------|----------|
| `ts_code` | 股票代码 | - |
| `trade_date` | 交易日期 | - |
| `vol` | 成交量 | `vol` |
| `amount` | 成交额 | `amount` |
| `open` | 开盘价 | `open` |
| 最高价 | `high` | `high` |
| `low` | 最低价 | `low` |
| `close` | 收盘价 | `close` |
| `pct_chg` | 涨跌幅 | `pct_chg` |
| `turnover_rate` | 换手率 | `turnover_rate` |
| `circ_mv` | 流通市值 | `circ_mv` |

## 命名一致性检查

### 因子命名模式

```python
# 资金流因子
df["lg_elg_net_buy_vol"]  # 大单+超大单净买入量
df["sm_net_buy_vol"]  # 小单净买入量
df["flow_divergence_ratio"]  # 资金流分歧比

# 筹码因子
df["chip_concentration_range"]  # 筹码集中度
df["chip_skewness"]  # 筹码偏度
df["floating_chip_proxy"]  # 浮筹比例代理

# 收益因子
df["return_5"]  # 5日收益率
df["return_20"]  # 20日收益率
```

### 模型命名

```python
# 推荐
my_catboost_model.cbm
best_model.pth

# 不推荐
model1.cbm
final.pth
```