QTradeProgram/README_命名规范.md

命名规范指南

概述

本文件定义了系统中文件、文件夹和类的命名规范，以确保代码的一致性和可读性。

命名原则

1. 一致性原则

• 相同类型的组件使用相同的命名模式
• 保持命名风格在整个系统中一致
• 避免混合使用不同的命名约定

2. 描述性原则

• 名称应清晰描述其功能或用途
• 避免使用缩写，除非是广泛接受的
• 使用完整的单词以提高可读性

3. 简洁性原则

• 在保持描述性的前提下尽量简洁
• 避免过长的名称
• 删除不必要的单词

文件夹命名规范

目录结构

Sqbase/
├── core/                    # 核心系统组件
├── data_processing/         # 数据处理组件（原 data/）
├── network_communication/   # 网络通信组件（原 network/）
├── configuration/           # 配置管理组件（原 config/）
├── utilities/               # 工具组件（原 utils/）
├── common_structures/       # 通用结构（原 common/）
├── interfaces/              # 接口定义
└── implementations/         # 实现文件

文件夹命名规则

• 使用小写字母
• 使用下划线分隔单词
• 名称应明确描述目录内容
• 避免使用缩写

文件命名规范

头文件 (.h)

• 使用 PascalCase（大驼峰命名法）
• 反映类名或主要功能
• 避免使用前缀，除非是框架要求

示例：

• DataBuffer.h（原 qdatabuffer.h）
• FaultToleranceManager.h（原 qfaulttolerance.h）
• ConfigurationManager.h（原 qconfigmanager.h）

实现文件 (.cpp)

• 与对应的头文件同名
• 使用相同的命名约定

示例：

• DataBuffer.cpp
• FaultToleranceManager.cpp
• ConfigurationManager.cpp

其他文件

• 文档文件：使用描述性名称和下划线分隔
• 配置文件：使用小写和下划线
• 资源文件：使用有意义的名称

类命名规范

类名

• 使用 PascalCase（大驼峰命名法）
• 使用名词或名词短语
• 反映类的职责和功能
• 避免使用前缀，除非是框架要求

示例：

• DataBuffer（原 QDataBuffer）
• FaultToleranceManager（原 QFaultTolerance）
• ConfigurationManager（原 QConfigManager）

接口类

• 使用描述性名称
• 可以以 "Interface" 或 "I" 开头（可选）

示例：

• IDataProcessor
• NetworkInterface

抽象基类

• 可以以 "Base" 或 "Abstract" 开头

示例：

• AbstractDataHandler
• BaseConnection

方法命名规范

方法名

• 使用 camelCase（小驼峰命名法）
• 使用动词或动词短语
• 清晰描述方法的操作

示例：

• initializeSystem()
• processOrderData()
• validateConfiguration()

访问器方法

• 获取方法：getProperty() 或直接 property()
• 设置方法：setProperty(value)
• 布尔方法：isValid(), hasData(), canProcess()

变量命名规范

成员变量

• 使用 camelCase（小驼峰命名法）
• 可以添加 m_ 前缀以区分成员变量

示例：

• m_bufferSize
• m_connectionState
• m_dataProcessor

局部变量

• 使用 camelCase（小驼峰命名法）
• 描述变量的用途

示例：

• currentPacket
• connectionStatus
• processedData

常量

• 使用 UPPER_CASE（全大写）
• 使用下划线分隔单词

示例：

• MAX_BUFFER_SIZE
• DEFAULT_TIMEOUT_MS
• SYSTEM_VERSION

枚举和结构体命名规范

枚举类型

• 使用 PascalCase（大驼峰命名法）
• 枚举值使用 PascalCase

示例：

enum class ConnectionState {
    Disconnected,
    Connecting,
    Connected,
    Degraded
};

结构体

• 使用 PascalCase（大驼峰命名法）
• 反映结构体的用途

示例：

struct ConnectionConfig {
    std::string serverAddress;
    int port;
    int timeoutMs;
};

命名空间规范

命名空间

• 使用小写字母
• 反映模块或功能区域

示例：

• trading_core
• data_processing
• network_communication

具体重命名方案

核心系统组件

• QTradeCore → TradingCore
• qtradecore.h → TradingCore.h

数据处理组件

• QDataBuffer → DataBuffer
• QDataQuality → DataQualityValidator
• QOrderProcessor → OrderProcessor
• QBigOrderManager → BigOrderManager

网络通信组件

• QFaultTolerance → FaultToleranceManager
• QSubscriptionManager → SubscriptionManager

配置管理组件

• QConfigManager → ConfigurationManager
• QLogManager → LogManager

工具组件

• QEventBus → EventBus
• ObjectPool → ObjectPool（保持不变）
• ordertypedelegate.h → OrderTypeDelegate.h

迁移计划

第一阶段：创建新命名文件

1. 使用新命名创建所有文件
2. 保持旧文件暂时存在
3. 更新包含关系

第二阶段：更新引用

1. 更新所有包含新文件的代码
2. 验证编译通过

第三阶段：清理旧文件

1. 删除旧命名文件
2. 更新构建配置

最佳实践

1. 可读性优先

• 选择最易理解的名称
• 避免技术术语，除非必要
• 考虑团队成员的背景

2. 保持一致性

• 在整个代码库中坚持相同的约定
• 定期进行代码审查以确保一致性
• 使用代码格式化工具

3. 文档化

• 为不明显的命名添加注释
• 维护命名约定文档
• 为新团队成员提供指导

4. 渐进式改进

• 不要一次性重命名所有内容
• 优先处理最常访问的组件
• 确保向后兼容性

工具支持

代码格式化

• 使用 clang-format 或类似工具
• 配置一致的格式化规则
• 在构建过程中自动格式化

静态分析

• 使用静态分析工具检查命名
• 设置命名约定检查规则
• 集成到 CI/CD 流程中

通过遵循这些命名规范，我们将创建一个更加一致、可读和可维护的代码库。