NewStock/.kilocode/rules/naming_conventions.md

命名约定规则

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

文件命名

Python 源文件

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

# 推荐
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)
• 名称应表达变量的含义
• 避免无意义的单字母（循环变量除外）

# 推荐
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)
• 定义在模块顶部或单独的常量文件

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

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

临时变量

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

# 推荐
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 名称修饰）
• 或单下划线前缀（约定私有）

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

函数命名

公共函数

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

# 推荐
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

私有函数

• 使用 单下划线前缀

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

数据处理函数

# 推荐：明确表达输入输出
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)
• 名词或名词短语

# 推荐
class FactorCalculator:
    pass

class DataProcessor:
    pass

class StockAnalyzer:
    pass

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

class data_processor:  # 违反 PascalCase
    pass

DataFrame 列命名

因子列

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

# 推荐：因子
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"]  # 获利盘价格区域

中间计算列

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

# 推荐
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_ 前缀

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

命名一致性检查

因子命名模式

# 资金流因子
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日收益率

模型命名

# 推荐
my_catboost_model.cbm
best_model.pth

# 不推荐
model1.cbm
final.pth