293 lines
5.4 KiB
Markdown
293 lines
5.4 KiB
Markdown
# 命名约定规则
|
||
|
||
本项目定义了统一的命名规范，确保代码可读性和一致性。
|
||
|
||
## 文件命名
|
||
|
||
### 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
|
||
```
|