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

**示例：**
```cpp
enum class ConnectionState {
    Disconnected,
    Connecting,
    Connected,
    Degraded
};
```

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

**示例：**
```cpp
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 流程中

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