260 lines
5.9 KiB
Markdown
260 lines
5.9 KiB
Markdown
# 命名规范指南
|
||
|
||
## 概述
|
||
|
||
本文件定义了系统中文件、文件夹和类的命名规范，以确保代码的一致性和可读性。
|
||
|
||
## 命名原则
|
||
|
||
### 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 流程中
|
||
|
||
通过遵循这些命名规范，我们将创建一个更加一致、可读和可维护的代码库。
|