# 代码格式化规则

本项目使用 Python 语言开发，以下是代码格式化规范。

## 缩进

- 使用 **4个空格** 进行缩进
- 不使用 Tab 字符

## 行长度

- 每行最大长度：**100 字符**
- 长的表达式可以换行，保持缩进一致

## 空行

- 类定义之间：**2个空行**
- 函数定义之间：**1个空行**
- 函数内部逻辑分段：**使用空行分隔逻辑块**
- 导入语句之后：**1个空行**

## 空格使用

```python
# 正确的写法
df = df.sort_values(by=["ts_code", "trade_date"])
result = (df["close"] - df["open"]) / (df["high"] - df["low"] + epsilon)

# 错误的写法
df=df.sort_values(by=["ts_code","trade_date"])
result=(df["close"]-df["open"])/(df["high"]-df["low"]+epsilon)
```

### 运算符周围

- 运算符两侧各加一个空格
- 括号内侧不加空格

```python
# 推荐
total_buy_vol = df["buy_sm_vol"] + df["buy_lg_vol"] + df["buy_elg_vol"]

# 不推荐
total_buy_vol=df["buy_sm_vol"]+df["buy_lg_vol"]+df["buy_elg_vol"]
```

### 函数调用

```python
# 推荐
df["atr_14"] = grouped.apply(
    lambda x: pd.Series(
        talib.ATR(x["high"].values, x["low"].values, x["close"].values, timeperiod=14),
        index=x.index,
    )
)

# 不推荐
df["atr_14"] = grouped.apply(lambda x: pd.Series(talib.ATR(x["high"].values, x["low"].values, x["close"].values, timeperiod=14), index=x.index))
```

## 括号

```python
# 推荐
conditions_winner = [
    (df["close"] > df["cost_85pct"]) & (df["winner_rate"] > 0.8),
    (df["close"] < df["cost_15pct"]) & (df["winner_rate"] < 0.2),
]

# 不推荐
conditions_winner = [(df["close"] > df["cost_85pct"]) & (df["winner_rate"] > 0.8), (df["close"] < df["cost_15pct"]) & (df["winner_rate"] < 0.2)]
```

## 字符串引号

- 使用 **双引号** `"` 作为字符串默认引号
- 字符串内部包含双引号时，使用单引号 `'`
- 多行字符串使用三引号 `"""` 或 `'''`

## 导入顺序

```python
# 1. 标准库
import numpy as np
import pandas as pd

# 2. 第三方库
import talib

# 3. 本地模块
from .utils import some_function
```

## 注释

### 行内注释

- 行内注释与代码之间间隔 **2个空格**
- 注释以大写字母开头

```python
epsilon = 1e-8  # 防止除零
```

### 块注释

- 用于复杂逻辑的说明
- 使用 `#` 而非 `"""`（后者用于 docstring）

```python
# 计算每只股票的滚动协方差
# 使用高成交量窗口和收盘价窗口
def calculate_rolling_cov(group):
    return group["high"].rolling(window_high_volume).cov(group["vol"])
```

### TODO 注释

```python
# TODO: 这个因子需要优化，可能导致过拟合
# FIXME: 修复浮点数精度问题
```

## Docstring

为所有公共函数、类和模块编写 docstring：

```python
def calculate_risk_adjusted_return(df, days=1, method="ratio", lambda_=0.5, eps=1e-8):
    """
    计算单只股票的风险调整收益。

    参数：
    - df: DataFrame，包含 'ts_code' 和 'close' 列
    - days: 预测未来多少天的收益
    - method: 'ratio' 或 'difference'
    - lambda_: 风险惩罚系数
    - eps: 防止除零的小常数

    返回：
    - 添加 'risk_adj_return' 列的 DataFrame
    """
    pass
```

## 数据管道格式化

对于复杂的数据处理链，使用链式调用并适当换行：

```python
df = (
    df.sort_values(by=["ts_code", "trade_date"])
    .groupby("ts_code", group_keys=False)
    .apply(lambda x: x["close"].pct_change().rolling(window=5).std())
)
```

## 异常处理

```python
try:
    result = df["close"] / (df["high"] - df["low"])
except ZeroDivisionError:
    result = 0
```