167 lines
3.5 KiB
Markdown
167 lines
3.5 KiB
Markdown
# 代码格式化规则
|
||
|
||
本项目使用 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
|
||
```
|