C++代码格式化工具clang-format详细介绍

clang-format

我曾在许多编程团队工作过，这些团队名义上都有“编程风格指南”。该指南经常被写下来并放置在开发人员很少查看的地方。几乎在每种情况下，样式指南都会被忽略，代码审查会演变为样式参数，并且源代码存储库内部会开发多种样式。

MongoDB 团队为我们提供了出色的格式化原则：

A formatting process which is both manual and insufficient is doomed to be abandoned.

我们不应该依赖程序员遵循一组规则，而应该自动化该过程，使其尽可能简单和客观。幸运的是，clang 团队创建了一个我们可以利用的出色工具：clang-format。通过使用 clang-format，我们可以创建样式规则列表，使程序员能够快速重新格式化其代码，并创建在我们的构建服务器上运行的格式检查以确保合规性。

思考代码风格指南

在开始这次冒险之前，为您的团队牢记一些风格指南非常重要。您可以使用您的团队忽略的便捷编程风格指南，也可以查看网络上的风格指南和规则，并决定您的团队应采用哪些规则。下一节提供了可供参考的样式指南列表。风格是一个有争议的话题。不要卷入不必要的争论。使用空格还是制表符最终并不重要，一旦一个工具客观地更新每个人的代码，它就根本不重要了。如果风格指南没有明确的赢家，则指定某人作为最终决策者。另请注意，该工具无法检查某些样式规则。考虑这样的规则是否最终重要并以其他方式执行。

生成您的配置

虽然您可以从头开始构建 clang 格式配置，但从现有样式开始并进行修改要容易得多。
您可以使用以下命令查看为每种默认样式启用的选项：

clang-format --style=llvm -dump-config

• llvm – complies with the LLVM coding standard
• Google – complies with Google’s C++ style guide
• Chromium – complies with Chromium’s style guide
• Mozilla – complies with Mozilla’s style guide
• WebKit – complies with Webkit’s style guide

选择文件作为基线后，将内容转储到 .clang 格式文件作为起始基线：

clang-format --style=llvm -dump-config > .clang-format

.clang_format 文件是我们保存自定义样式定义的位置。将来运行 clang-format 时，我们将指定 -style=file 以便 clang-format 知道使用我们的自定义规则。
现在您已经有了基线，请检查样式选项并针对您的项目进行调整。您需要根据代码检查格式化样式规则，以确保输出按预期工作。您还可以使用在线 .clang 格式生成器来获得更具交互性的体验。交互式构建器中的许多样式选项都使用实时示例来让您比较不同的设置。请注意，最新 clang-format 版本中可用的某些选项可能在在线构建器中不可用。

运行 clang-format

运行 clang-format 相对简单。在讨论细节之前，让我们先讨论一些重要的选项。

风格

style 参数用于确定 clang-format 将应用的样式规则。您可以使用上述任何样式，或 -style=file 告诉 clang-format 它必须使用您的 .clang-format 文件。

直接编辑

默认情况下，clang-format 会将格式差异显示为 shell 输出。我更喜欢直接使用 clang 格式更新文件。使用 -i 选项启用此行为。

默认配置

开始使用 clang-format 时，很容易遇到 clang-format 找不到您的样式文件的情况。在这种情况下，它将回退到 LLVM 风格。您可以使用-fallback-style=<style>开关确定用作后备的确切样式。如果找不到您的文件，将<style>设置为 none 会导致 clang-format 失败：

-fallback-style=none

重新格式化文件
在撰写本文时，我们需要提供文件列表，因为 clang-format 不会在源树上递归运行。在下一篇文章中，我将提供一些 clang-format 的示例包装脚本。
下面是一个入门命令，它可以查找当前目录树中的所有 C 和 C++ 文件：

find . -iname *.h -o -iname *.c -o -iname *.cpp -o -iname *.hpp \| xargs clang-format -style=file -i -fallback-style=none

注意与clang-Format一起使用的参数：我已经应用了就地编辑，指出样式规则在我的.clang-Format文件中，如果找不到样式文件，我希望clang-Format失败。

禁用一段代码的格式设置

当然，在某些情况下，我们不希望 clang-format 覆盖现有格式。也许无法创建格式化规则来允许所需的格式，或者出于可读性原因对块进行了特殊格式化。
您可以在代码中使用注释来禁止 clang-format 修改代码部分：

// clang-format off
void unformatted_code:
// clang-format on

clang-format的设置预览

用于交互式设计您的配置的网站

pre-commit