3. 代码规范与风格：Qt编码规范、代码审查与自动化工具

聊到Qt项目的代码规范，我第一个想到的就是「混乱」。

刚入行那几年，我接手过一个老项目。打开源码一看，有的类名用驼峰，有的用下划线；有的缩进是4空格，有的是Tab。最要命的是注释——几乎为零。那段时间我每天的工作就是猜代码意图，效率低得让人抓狂。

后来我慢慢明白了一个道理：代码规范不是束缚，而是解放。它让团队协作变得顺畅，让维护成本直线下降。今天我就把这几年的经验梳理一下，希望能帮你少走弯路。

3.1 Qt编码规范：命名、缩进、注释

Qt官方其实有一套很成熟的编码风格，我建议直接沿用。没必要自己发明一套，除非你想让新同事花一周时间适应。

3.1.1 命名规范

命名这件事，说白了就是「见名知意」。我见过有人用 a、b、c 命名变量，三个月后自己都看不懂。

3.1.2 缩进与格式

缩进问题，团队里最容易吵架。我的建议是：统一用4空格，不用Tab。为什么？因为不同编辑器对Tab的解析不一样，4空格在任何地方看起来都一样。

// 好的缩进风格
void MainWindow::onButtonClicked()
{
    if (m_isEnabled) {
        QMessageBox::information(this, "提示", "按钮已点击");
    } else {
        qDebug() << "按钮被禁用";
    }
}

// 不好的风格——缩进混乱
void MainWindow::onButtonClicked()
{
  if (m_isEnabled) {
        QMessageBox::information(this, "提示", "按钮已点击");
    } else {
      qDebug() << "按钮被禁用";
        }
}

嗯，这里要注意：Qt Creator默认就是4空格缩进。如果你用其他IDE，记得改一下设置。

3.1.3 注释规范

注释不是越多越好。我见过有人给 int i = 0; 写注释「定义整数i并赋值为0」——这纯属浪费生命。

好的注释应该回答「为什么」，而不是「是什么」。

// 好的注释：解释为什么这么做
// 使用异步加载，避免UI线程阻塞
void loadLargeFile(const QString &filePath);

// 不好的注释：废话
// 这个函数用来加载文件
void loadLargeFile(const QString &filePath);

3.2 代码审查流程

代码审查（Code Review）这件事，我刚开始也觉得是浪费时间。直到有一次，我提交了一段看似完美的代码，结果同事一眼就看出了潜在的线程安全问题。

从那以后，我再也不敢轻视代码审查了。

3.2.1 审查流程

1. 提交前自检：自己先过一遍代码，确保没有低级错误
2. 创建Pull Request：描述清楚改动内容和原因
3. 指定审查人：至少2人，避免单人盲区
4. 审查与反馈：审查人逐行检查，给出建议
5. 修改与确认：开发者根据反馈修改，再次提交
6. 合并代码：所有问题解决后，合并到主分支

3.2.2 审查清单

我整理了一份审查清单，每次审查时对照检查：

• 代码是否遵循Qt编码规范？
• 是否存在内存泄漏风险？（new/delete是否成对）
• 信号与槽的连接是否正确？（参数类型是否匹配）
• UI线程是否被阻塞？（耗时操作是否放在子线程）
• 异常情况是否处理？（空指针、边界值）
• 注释是否清晰且必要？

3.3 静态分析工具：Clazy与Clang-Tidy

人工审查总有疏漏，这时候就需要工具来帮忙了。静态分析工具就像代码的「体检医生」，能自动发现潜在问题。

3.3.1 Clazy

Clazy是专门为Qt设计的静态分析工具。它能检测出很多Qt特有的问题，比如信号槽连接错误、QString使用不当等。

# 使用Clazy分析项目
clazy-standalone -p build_dir -o report.yaml

# 或者在CMake中启用
set(CMAKE_CXX_CLANG_TIDY "clazy")
target_compile_options(myapp PRIVATE -Wno-clazy-*)
target_compile_options(myapp PRIVATE -Wclazy-*)

# 常用检查项
# - clazy-qstring-arg: 检查QString::arg()使用是否正确
# - clazy-old-style-connect: 检查旧式信号槽连接
# - clazy-connect-by-name: 检查connect()中的名称匹配

3.3.2 Clang-Tidy

Clang-Tidy是更通用的C++静态分析工具。它检查的范围更广，包括代码风格、性能问题、潜在bug等。

# 使用Clang-Tidy分析单个文件
clang-tidy main.cpp -- -I/path/to/headers

# 在CMake中集成
set(CMAKE_CXX_CLANG_TIDY "clang-tidy;--checks=*,-cppcoreguidelines-*")

# 常用检查项
# - modernize-*: 现代化C++写法检查
# - performance-*: 性能相关检查
# - bugprone-*: 潜在bug检查

3.4 自动化格式化：clang-format

代码格式问题，靠人工检查太累了。我推荐用 clang-format 来自动格式化代码。它支持Qt风格，配置好之后一键搞定。

3.4.1 配置文件

在项目根目录创建 .clang-format 文件：

BasedOnStyle: Qt
IndentWidth: 4
UseTab: Never
BreakBeforeBraces: Allman
AllowShortFunctionsOnASingleLine: None
ColumnLimit: 100
PointerAlignment: Left
AccessModifierOffset: -4

3.4.2 集成到开发流程

我建议把格式化步骤集成到Git钩子中，这样每次提交代码时自动格式化：

# .git/hooks/pre-commit
#!/bin/bash
files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(cpp|h)$')
for file in $files; do
    clang-format -i "$file"
    git add "$file"
done

3.5 知识体系总览

下面这张图是我整理的Qt代码规范知识体系，你可以把它当作一个检查清单：

这张图把整个知识体系串起来了。你可以看到，编码规范是基础，代码审查是流程保障，静态分析工具和自动化格式化是技术手段。四者配合，才能构建一个健康的代码环境。