Xenia Canary 代码风格指南解析：C++ 与 Android 双栈的工程化规范实践

本指南以 Xenia Canary（Xbox 360 模拟器研究项目）官方 代码风格指南 为核心，系统讲解项目在 C++ 与 Android 两条技术栈上执行的格式化与静态检查规范：包括 "clang-format + Google Style" 的总纲、xb format/xb lint 工具链的完整用法、构建机器人（Buildbot）的自动校验机制，以及 Android 侧 Java/XML/Groovy 的差异化排版规则。读完本文，你将掌握在 Xenia Canary 仓库中提交代码前必须执行的格式化命令、参数含义与编辑环境配置方法，并能对照仓库源码理解每条规则背后的工程动机。

总纲：clang-format with Google Style

Xenia Canary 的 C++ 风格可以浓缩为一句话：

The style guide can be summed up as 'clang-format with the Google style set'.

即以 clang-format 配合 Google Style 作为唯一格式化基准。在此基础上，项目同时遵循 Google 官方 C++ Style Guide，并将 cpplint 作为最终裁决依据（source of truth）。当遇到规则冲突或歧义时，文档给出的最终判断标准是：

When in doubt, defer to what code in the project already does.

——以仓库现有代码的写法为准。这意味着新贡献者在不确定某处该怎样排版时，最可靠的做法是去 src/xenia/ 下阅读同类型既有代码，模仿其写法。

基础规则清单

文档明确列出的 C++ 基础规则包括：

规则项	要求
行宽	每行最多 80 列（80 column line length max）
换行符	统一使用 LF（Unix 风格），禁止 CRLF
缩进	2 空格软缩进，严禁使用 TAB 字符
命名与大小写	遵循 Google Style Guide 的命名/大小写约定
include 排序	按 Google Style Guide 的 include 顺序规则排序
注释	注释必须正确使用标点（大写开头、句号结尾等）
TODO 归属	TODO 必须署名，格式为 // TODO(yourgithubname): foo.

其中 "no TABs" 是硬性要求——混入 TAB 会直接破坏 clang-format 的确定性输出；TODO 署名规则则是为了保证后续维护者能找到责任人与上下文。

为什么必须严格统一？

文档引用了 Google Style Guide 的核心理由：通过强制一致性，使任何程序员都能快速读懂他人代码，并利用 "pattern-matching"（模式匹配）推断符号含义与不变量。Xenia Canary 进一步给出了一个工程化的硬约束：

Code that really breaks from the formatting rules will not be accepted, as then no one else can use clang-format on the code without also touching all your lines.

即：严重偏离格式化规则的代码将不被接受。原因很实际——一旦某段代码不符合规范，其他人对整个文件执行 clang-format 时就会连带改动你的所有行，产生大量无意义 diff，破坏代码审查与合入历史。

仓库中的 .clang-format 配置解读

根目录的 .clang-format 是上述规则的可执行化载体，仓库实际采用的配置如下：

---
BasedOnStyle: Google
DerivePointerAlignment: false
PointerAlignment: Left
SortIncludes: true
KeepEmptyLines:
  AtStartOfFile: false
InsertNewlineAtEOF: true
InsertBraces: true

# Regroup causes unnecessary noise due to clang-format bug.
IncludeBlocks: Preserve

---
Language: Java
DisableFormat: true
SortIncludes: false

配置要点与文档规则的对应关系：

• BasedOnStyle: Google——直接继承 Google Style 基准，与文档"clang-format with the Google style set"一一对应；
• PointerAlignment: Left 配合 DerivePointerAlignment: false——指针/引用符号统一靠左（int* x），且禁止根据上下文推导指针位置，保证全仓库指针写法绝对一致；
• SortIncludes: true——自动按 Google 规则排序 include；
• IncludeBlocks: Preserve——保留 include 之间的空行分组（注释说明 Regroup 会因 clang-format 的已知 bug 产生无谓噪音，故禁用）；
• InsertBraces: true——强制为单语句 if/for/while 等补全花括号，与 Google 风格对花括号的偏好一致；
• InsertNewlineAtEOF: true——保证文件末尾换行（POSIX 惯例）；
• Java 段落：DisableFormat: true——显式关闭对 Java 文件的 clang-format 处理，这正是文档"Android Java 代码不做自动格式化校验"这一策略的配置体现，Java 风格交由 Android Studio/AOSP 规则管理。

此外，仓库在生成的字节码目录下还放置了局部覆盖配置，例如 src/xenia/gpu/shaders/bytecode/.clang-format：

DisableFormat: true
SortIncludes: false

这说明：由构建脚本生成的 shader 字节码头文件（xb buildshaders 产物）不参与 clang-format 检查，因为它们由工具生成、人工不可控。这与 xb 脚本中扫描源文件时排除 bytecode 目录的行为（见下文 find_xenia_source_files）互相印证。

xb 工具链：format / lint / style / tidy 全命令解析

Xenia Canary 将全部格式化与检查能力封装在仓库根的 xb（Python 主构建脚本）中，通过子命令对外暴露。脚本在 discover_commands() 中注册了 lint、format、style、tidy 四个与代码风格相关的命令（xb）。

clang-format 二进制探测

无论是 xb lint 还是 xb format，都会先调用 get_clang_format_binary()（xb）定位可用的 clang-format，其探测逻辑值得注意：

• 版本下限：要求 clang-format 19 或更新（clang_format_version_min = 19），低于 19 直接报错退出；
• 优先高版本：从 clang-format-21 向下探测到 clang-format-19，再回退到通用名 clang-format，取找到的最高版本；
• Windows 特有路径：会额外检查 Visual Studio 自带的 LLVM 工具链（VCINSTALLDIR\Tools\Llvm\x64\bin\clang-format.exe）以及默认安装的 ProgramFiles\LLVM\bin\clang-format.exe——这正是文档所说"安装到默认位置时 xb format 会自动找到它"的实现细节。

⚠️ 版本说明：风格指南文档中提到的 "The buildbot is running LLVM 3.8.0" 是历史信息。当前仓库 xb 脚本已将 clang-format 的版本下限提升到 19，本地开发时应以脚本实际要求为准（运行 xb format/xb lint 时脚本会打印实际使用的 clang-format 版本）。若本地 lint/format 结果与 CI 不一致，请优先核对 clang-format 版本。

xb lint：只报告、不修改

lint 命令（xb）用于检查代码是否合规，绝不自动修改。它支持两个参数：

• xb lint --all：检查 src/ 下全部源文件；
• xb lint --origin：仅检查相对 origin/canary_experimental 分支有改动的文件（--commit 指向 origin/canary_experimental）。

其实现分两条路径：

1. 全量模式（--all）：通过 find_xenia_source_files()（xb）收集 src/ 下所有 .cc/.c/.h/.inl/.inc 文件，逐个执行 clang-format -output-replacements-xml -style=file，只要输出 XML 中出现 <replacement 即判定该文件不合规；随后调用 tools/diff.py（基于 Python difflib.unified_diff 的轻量 diff 工具）展示格式差异，最后提示：

   ERROR: 1+ diffs. Stage changes and run 'xb format' to fix.
   

2. 增量模式（默认 / --origin）：调用仓库自带的 third_party/clang-format/git-clang-format 执行 --diff，基于 git 提交范围计算改动文件的格式差异。默认以 HEAD 为基准，--origin 时以 origin/canary_experimental 为基准。

xb format：自动修复格式

format 命令（xb）与 lint 互补，用于实际重排代码，参数一致：

• xb format：用 git-clang-format 格式化相对 HEAD（或 origin/canary_experimental）改动的文件；
• xb format --all：对 src/ 下全部 .cc/.c/.h/.inl/.inc 文件执行 clang-format -i -style=file（-i 为原地改写）；
• xb format --origin：格式化相对 origin/canary_experimental 改动的文件。

格式化完成后脚本会提示：

Files were formatted. Please stage the changes:
  git status
  git add <files>

xb style：cpplint 静态检查

style 命令（xb）运行仓库自带的 third_party/cpplint/cpplint.py 对全部源文件（排除 _test.cc）做 Google 风格静态检查，实际参数为：

cpplint.py --output=vs7 --filter=-build/c++11,+build/include_alpha --root=src <files...>

其中 --filter=-build/c++11 关闭 c++11 相关告警，+build/include_alpha 强制开启 include 按字母序检查（呼应基础规则中的 include 排序要求），--root=src 指定代码根目录。这就是文档中 "cpplint is the source of truth" 的具体落点。

xb tidy：clang-tidy 深度检查

作为补充，tidy 命令（xb）运行 clang-tidy，检查类别包括 clang-analyzer-*、google-*、misc-*、modernize-*（readability-* 被 TODO 注释标注为暂缓），并支持 --fix 自动应用修复。它需要先通过 cmake configure 生成 compile_commands.json，说明 tidy 是需要编译数据库的静态分析，比纯格式化检查更重，适合合入前深扫。

Buildbot 自动校验：CI 如何守护风格

风格指南文档明确了构建机器人的自动校验策略，这是所有贡献者必须提前知晓的"红线"：

• 构建机器人会在 master（canary_experimental）分支上运行 xb lint --all，全量检查；
• 对 Pull Request 运行 xb lint --origin，只检查 PR 改动的文件；
• 因此文档建议：每次本地提交前先跑 xb format，保持改动始终合规，否则可能被迫 rebase；
• 若提交后才发现格式问题，补救方式是执行 xb format --origin 然后 rebase 合并这些格式化改动——避免出现"5 个功能提交 + 1 个 '哎呀忘了格式化' 的补救提交"这样糟糕的提交历史。

这一流程确保 CI 的 lint 检查永远只针对真实改动，且历史保持整洁。

编辑器集成：让格式化不再占用脑力

文档给出的建议是：把 clang-format 接入编辑器，彻底不用再想 TAB、换行和折行问题。

命令行使用

xb format 依赖 PATH 上的 clang-format。Windows 用户可通过 LLVM 官方二进制包安装，安装到默认位置时 xb 脚本会自动找到（对应上文 get_clang_format_binary() 中 ProgramFiles\LLVM\bin 的探测逻辑）。

Visual Studio

安装官方 LLVM/Clang 插件后，通过 Tools → Options → LLVM/Clang → ClangFormat 将 Style 设为 Google，用 Ctrl-R / Ctrl-F 触发格式化。文档提示该插件默认只格式化光标处，全文件格式化需先全选再触发。

Xcode

可通过插件管理器安装 ClangFormat 插件，设置为 Google 风格并"format on save"，之后彻底不再手动处理缩进与换行。这些编辑器集成思路与根目录 .clang-format 的 BasedOnStyle: Google 完全一致——IDE 读取到的正是同一份配置。

Android 风格指南：差异化但目标一致

Xenia Canary 的 Android 端（位于 android/android_studio_project）采用与 C++ 不同的格式化规则，原因是工程目标不同——Android 侧追求"快速搭好开发环境"，因此直接对齐 AOSP Java Code Style 与 Android Studio 默认设置，而非强推 clang-format 式单一输出。

Java：100 字符行宽与 8 空格续行

Java 规则要点：

• 每行限制 100 字符（区别于 C++ 的 80 列）；
• 赋值语句放不下时，右侧表达式另起一行、8 空格缩进；
• 方法声明或调用的参数列表过长时，整个参数列表另起一行、8 空格缩进——这是与 C++ 风格的明显差异：C++ 中参数可以与左括号对齐，Java 中则固定为 8 空格缩进；
• 遵循 "rectangle rule"：表达式在视觉上构成嵌套的"包围矩形"层级，块内容 4 空格缩进、子表达式 8 空格缩进。

仓库中的 LauncherActivity.java 是这些规则的直接范例——onActivityResult 方法签名因参数列表过长，将整个参数列表换行并按 8 空格缩进：

@Override
protected void onActivityResult(
        final int requestCode, final int resultCode, final Intent data) {

注意：续行使用 8 空格（等于两层 4 空格缩进），而非与 ( 对齐，这正是文档强调的 Java 与 C++ 的排版分歧点。

XML：属性独立成行

XML 规则要点：

• 元素行宽超过 100 字符、或属性较多时，每个属性各占一行、4 空格缩进；
• 唯一的例外是第一个 xmlns 命名空间声明，必须与元素名保持在同一行。

仓库的 activity_launcher.xml 严格遵循该模式：xmlns:android 与 xmlns:tools 均留在根元素首行，其余属性（layout_width、layout_height、tools:context 等）逐个独立成行并以 4 空格缩进：

<ScrollView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="jp.xenia.emulator.LauncherActivity">

Groovy：单引号优先

Groovy（Gradle 构建脚本）规则：

• 块使用 4 空格缩进，多行拆分的参数使用 8 空格缩进；
• 字符串字面量优先使用单引号，除非需要字符串插值（"..." 形式）。

依靠 Android Studio 而非自动格式化

与 clang-format "只允许唯一排版"的强约束不同，Android Studio 会保留代码中原有的多种风格选择，因此文档建议：

• 用 Code → Reformat Code 与 Code → Reformat File 应用粗粒度格式规则（覆盖 Java、XML、Groovy）；
• 不要完全依赖自动格式化，手工逼近最终风格；
• 用 Code → Rearrange Code 维持 Java 类声明的统一结构顺序。

Android 侧不设自动格式化校验（根目录 .clang-format 中 Java 段 DisableFormat: true 正是这一策略的配置证据），风格把关主要依赖开发者自觉与 AOSP 规则。

总结：把规范变成工作流

Xenia Canary 的风格治理可以归纳为"规则文档 + 可执行配置 + CI 强制"三层：

1. 规则层：docs/style_guide.md 定义 C++（clang-format + Google Style + cpplint）与 Android（AOSP + Android Studio 默认）两套规范；
2. 配置层：根目录 .clang-format 将 C++ 规则固化为机器可执行的格式，bytecode 子目录用 DisableFormat: true 豁免生成代码；
3. 强制层：xb 脚本提供 format（修复）、lint（检查）、style（cpplint）、tidy（clang-tidy）四类命令，构建机器人对 master 全量 lint、对 PR 增量 lint。

对贡献者而言，最简工作流就是：提交前跑 xb format → 检查 git diff → 合入前确保 xb lint --origin 通过。这套机制保证了 Xenia Canary 数万行 C++/Java/XML/Groovy 代码在多人协作下仍能保持"任何程序员都能快速读懂他人代码"的可维护状态。