Coding Standards

编码规范

风格来源

本仓编码风格借鉴并适配自 MongoDB 仓库，结合现代 C++23 特性和本项目需求进行的剪裁与优化。

---

基本规则

项目	规范
语言标准	C++23
编译器	GCC 15 / Clang 21（开发与生产统一）
格式化	.clang-format（基于 LLVM，4 空格缩进，列宽 100）
静态分析	.clang-tidy

格式化命令

./scripts/core/lint format   # 全量格式化
./scripts/core/lint check    # 只检查（不修改）

---

命名约定

元素	风格	示例
代码文件/目录	snake_case	file_parser.h, src/utils/
文档	kebab-case	docs/dev/git-guidelines.md
脚本	kebab-case	scripts/core/install-deps
类/结构体	PascalCase	class FastQReader;
函数/方法	camelCase	void processBatch();
变量（局部/参数）	camelCase	int readCount = 0;
类成员变量	camelCase + 尾部下划线	filePath_, impl_
常量	kConstantName	constexpr int kMaxReads = 1000;
命名空间	snake_case	namespace fq::utils

命名例外

以下文件名为行业惯例/工具约定，不纳入 snake_case 约束：

• README.md / CHANGELOG.md / LICENSE / CODE_OF_CONDUCT.md / CONTRIBUTING.md
• CMakeLists.txt / Dockerfile / docker-compose.yml / conanfile.py

---

代码组织

目录结构

include/fqtools/     # 公共 API 头文件
src/                 # 内部实现代码
src/cli/             # 命令行入口
src/cli/commands/    # 子命令实现
src/processing/      # 处理逻辑（Mutators, Predicates）
src/statistics/      # 统计分析逻辑
src/io/              # 输入输出处理

头文件包含顺序

1. C++ 标准库
2. 第三方库
3. 本项目其他模块

接口设计

• 头文件只包含声明
• 实现细节放在源文件中
• 使用 #pragma once 防止重复包含

---

现代 C++ 实践

资源管理

// 优先使用智能指针
std::unique_ptr<Processor> processor = create_processor();
std::shared_ptr<Config> config = std::make_shared<Config>();

// 禁止裸露的 new/delete

函数声明

// 统一使用尾随返回类型
auto processBatch(const Batch& batch) -> Result;

错误处理

// 优先使用异常
if (!is_valid(input)) {
    throw InvalidInputError("Invalid input file");
}

字符串处理

// 优先使用 string_view 作为只读参数
auto process_sequence(std::string_view sequence) -> bool;

C++23 特性

• std::ranges 约束模板参数（如 SequenceUtils::gcContent）
• 结构化绑定
• std::expected（错误处理增强）

---

CLI 规范

命令命名

• 子命令: 简短动词或名词（stat, filter）
• 命令类: PascalCase + Command 后缀（StatCommand）

选项格式

类型	格式	示例
长选项	kebab-case	--min-quality, --input
短选项	单字母	-i, -o, -t
布尔开关	正向选项	--verbose（必要时 --no-*）

全局选项

• -v, --verbose: 详细日志
• -q, --quiet: 仅错误输出
• --log-level=LEVEL: 显式设置日志级别

---

工具脚本规范

#!/bin/bash
set -euo pipefail  # 严格模式

# 函数命名: snake_case
print_info() {
    echo "INFO: $*"
}

# 变量引用: 双引号
run_build "$compiler" "$build_type"

统一工具入口：

脚本	用途
scripts/core/lint	代码质量检查
scripts/core/build	构建管理
scripts/core/test	测试运行

---

文档规范

API 文档

/**
 * @brief 处理 FASTQ 批次数据
 * @param batch 要处理的批次数据
 * @return 处理结果
 * @throws ProcessingError 处理失败时抛出
 */
auto processBatch(const Batch& batch) -> Result;

代码注释

• 对复杂逻辑添加必要注释
• 避免显而易见的注释
• 保持注释与代码同步

---

相关页面

• Contributing Guide — Git 提交规范与开发流程
• Build and CI — 构建系统与代码质量检查
• Architecture — 代码组织与模块设计