Android C++ 编码规范指引

作者：袖梨 2026-07-17

本指南旨在规范 Android C++ 开发，核心强调内存安全、接口清晰、跨平台性及高可维护性。通过工具强制执行命名、注释与格式规范，确保代码在 AOSP 规模下的高性能与稳健。

1. C++ 版本与基础规则

1.1 C++ 版本：为什么是 C++20？

核心逻辑：Google 和 Android 团队通过推动版本升级，旨在利用现代 C++ 的特性来消除旧版本中常见的 Bug（如内存泄漏、未定义行为）。
为什么“禁止超出范围”？
- 编译一致性：大型 Android 项目由数千名开发者维护。如果允许个人随意使用 C++23 甚至更高版本，会导致不同模块间的二进制接口（ABI）不兼容，或者因为构建环境（NDK版本）不一致导致编译失败。
- 稳定性：新标准特性往往在编译器（Clang/LLVM）中的支持深度不同，限制版本是为了确保所有模块都能在当前 Android 构建链（Toolchain）下稳定产出。
开发建议：关注 Android.bp 文件中的 cpp_std 设置。如果你想用新特性，请先确认当前的 NDK 版本是否完全支持。

1.2 非标准编译器扩展

含义：指编译器（主要是 Clang）提供的一些“特有功能”，例如某些 GNU 特有的内建函数、特定架构的语法糖等。
为什么要严禁？
- 锁定供应商：使用非标准扩展会让你被深度绑定在特定的编译器版本上。如果未来 Android 系统切换了编译后端，或者升级了底层组件，你的代码就会因为“非法语法”而大面积崩溃。
- 可移植性陷阱：当你想要复用这些代码到 Android 以外的环境（如 Linux 服务端或 Windows 工具链）时，这些扩展会成为移植的噩梦。
实操原则：如果你发现自己必须写类似 __attribute__((...)) 这种非标准关键字，请务必先思考：有没有标准的 C++ 替代方案？ 如果没有，将其封装在特定的宏中，并标注清楚平台依赖。

1.3 移植性

背景：Android 系统的特殊性在于它横跨了多种架构：
- CPU 架构：ARM64 (绝大多数设备)、ARM32 (旧设备)、x86_64 (模拟器)。
- 系统环境：NDK (原生开发包) 的环境与标准的 Desktop Linux 环境存在差异（比如 Bionic Libc 与 glibc 的细微区别）。
关键准则：
- 避免硬编码：严禁硬编码内存对齐方式、字节序 (Endianness)、或者整型大小（如假设 int 一定是 32 位）。使用 <cstdint> 中的 <int32_t>, <uintptr_t> 等标准类型。
- 内存对齐与 Padding：不要假设结构体在所有平台上内存布局都完全一致。在进行二进制数据传输时，必须显式定义序列化格式。
为什么移植性很重要？
- 当 Android 升级指令集架构（如推动纯 64 位系统）时，不注意移植性的代码会产生隐蔽的内存访问异常（SIGBUS/SIGSEGV）。

2. 头文件

2.1 自包含头文件

核心逻辑：头文件必须是“开箱即用”的。
深度解释：一个好的 .h 文件在包含其所有必要依赖后，应该能够单独通过编译（即 g++ -c my_header.h 不报错）。
为什么重要：如果头文件不自包含，调用者必须了解其内部的依赖链。一旦依赖关系发生变化，所有调用方都会被破坏，这会导致“牵一发而动全身”的编译灾难。

2.1 #define防御

核心逻辑：防重定义
深度解释：在复杂项目中，一个头文件可能会通过不同的路径被多次 #include。没有防御机制，编译器会重复定义类、函数或变量，触发报错。
规范化建议：使用工程名+路径+文件名作为唯一标识符
注意：#pragma once 虽然被广泛支持，但 Google C++ 指南基于可移植性（非标准）仍推荐使用宏防御。

2.3 IWYU原则

核心逻辑：用什么包含什么，杜绝“隐式依赖”。
深度解释：禁止依赖传递。如果 A.h 包含了 B.h，你绝不能因为引用了 A.h 就直接使用 B.h 中的符号。
实操建议：
- 如果你在 .cc 中使用了 std::vector，哪怕它在某个已包含的头文件中被间接引用了，你也必须在 .cc 中显式添加 #include <vector>。
- 优点：这使得删除冗余 include 变得安全且简单，自动化构建工具（如 clang-tidy 的 IWYU 检查）能够精确工作。

2.4 前向声明

核心逻辑：以极小的代价告知编译器“有这个类”。
深度解释：
- 什么时候用：当你在头文件中只需要使用某个类的指针或引用作为成员变量，而不需要调用其具体成员函数或获取其大小（sizeof）时。
- 编译器行为：前向声明只告知编译器存在一个类，不需要读取该类的头文件。这能显著缩短 Android 庞大依赖树的编译时间。
禁区：如果你需要调用该类的具体方法，或定义一个具体的对象实体（栈内存分配），必须使用 #include，不能仅用前向声明。

2.5 头文件内定义

核心逻辑：仅允许“编译期逻辑”留在头文件中。
深度解释：
- Inline 函数：定义在头文件中以提示编译器进行展开，减少函数调用开销。
- 模板：由于模板是在编译期实例化的，编译器必须在调用点看到完整的定义，因此它们必须放在头文件中。
- 严禁事项：绝对不要在头文件中定义常规的普通函数或非静态变量，否则在多个 .cc 文件包含该头文件时，链接器会报“符号重定义”错误（Multiple Definition Error）。

3. 作用域

3.1 命名空间

核心逻辑：所有代码必须放入命名空间。
深度解释：Android 系统中存在大量第三方库和不同的模块，如果所有符号都暴露在全局（Global Namespace），极易导致链接冲突。
最佳实践：使用具有项目辨识度的命名空间，例如 android::hardware::audio::。
避坑指南：严禁在头文件中使用 using namespace xxx;，这会强行污染包含该头文件的所有其他文件，引发不可控的命名冲突。

3.2 内部链接

核心逻辑：通过匿名命名空间（namespace { ... }）将代码的可见性限制在单个 .cc 文件内。
深度解释：编译器会将匿名命名空间内的符号视为当前文件的私有成员，链接器不会将其暴露给外部。
为什么重要：它能有效减小生成的 .so 文件体积（符号表变小），并防止不同文件间的函数名重复。

3.3 非成员/静态函数

核心逻辑：优先考虑封装在命名空间内的非成员函数，而非“全局”函数。
深度解释：如果一个函数不需要访问类的私有成员，就不应该写成成员函数；如果它只在当前文件使用，请使用 static 修饰或放入匿名命名空间。
优势：减少了类的耦合度，让代码逻辑更清晰。

3.4 局部变量

核心逻辑：变量作用域越小越好，且必须立即初始化。
深度解释：
- 作用域最小化：例如 for 循环中定义的迭代器，不要提到循环外。
- 声明即初始化：严禁“先声明，后赋值”的坏习惯。
为什么重要：Android 开发中，内存分配敏感，通过缩小作用域，可以保证变量的生命周期最短，降低内存占用，且极大减少了“未初始化变量”带来的诡异 Bug。

3.5 全局与静态变量

核心逻辑：严禁定义复杂的静态对象，除非是 POD（Plain Old Data，如数字、简单的 struct）。
深度解释：
- 静态初始化顺序问题：如果在不同文件定义了多个复杂的全局静态对象，它们之间的初始化顺序是未定义的。这会导致在 main() 函数运行前，程序就已经因为互相依赖而 Crash。
- 复杂对象：不要用 static std::vector 或 static MyClass 这种会导致运行时动态初始化的对象。

3.6 thread_local

核心逻辑：慎用，仅在确有必要时使用。
深度解释：thread_local 虽然能解决多线程数据隔离问题，但它会给编译器和链接器带来额外的复杂性，且在大量线程切换的 Android 服务中，频繁访问 thread_local 变量可能成为性能热点。
原则：优先通过函数参数传递上下文，而非使用隐式的线程全局变量。

4. 类

4.1 构造函数行为

核心逻辑：构造函数应当“轻量化”。
深度解释：构造函数不能执行会失败（抛出异常或返回错误码）的操作，因为 C++ 析构函数在构造失败时不会被调用，这会导致资源泄漏。
最佳实践：如果对象需要“启动”或“连接网络”，请提供一个 Init() 方法。

4.2 隐式转换

核心逻辑：强制所有单参数构造函数使用 explicit 关键字。
深度解释：C++ 默认允许编译器自动进行类型转换（例如：MyClass a = 10; 会将 10 隐式构造为 MyClass）。这经常导致极其隐蔽的 Bug。
规范：任何接受一个参数的构造函数，务必加上 explicit，除非你明确希望该类型可以被隐式转换为你的类。

4.3 可复制/可移动

核心逻辑：遵循“三/五法则”（Rule of Three/Five）。
深度解释：如果不显式声明，编译器会为你生成默认的复制/移动构造函数。如果你的类管理了资源（如文件句柄、原始指针），默认的浅拷贝会引发重复析构导致的 Crash。
建议：如果不需要拷贝，使用 = delete 明确禁用；如果需要，务必显式实现。

4.4 结构体 vs 类

核心逻辑：区分“纯数据”与“行为对象”。
深度解释：
- struct：仅用于存放数据的集合（POD），没有任何复杂的函数逻辑。
- class：用于封装实现、维护不变量、提供接口的逻辑对象。
规范：如果你的 struct 开始包含方法或复杂的逻辑，请立刻将其转换为 class。

4.5 继承

核心逻辑：组合优于继承 (Composition over Inheritance)，override 强制化。
深度解释：
- 继承：容易造成深度过大的类层次结构，导致维护灾难。
- 组合：通过包含其他对象来实现功能，代码更灵活、解耦。
- override：必须在重写虚函数时使用该关键字，防止因为函数签名微小差异（如 const 修饰符不同）导致并未实际覆盖父类方法。

4.6 运算符重载

核心逻辑：语义要自然，且保持对称性。
深度解释：不要为了酷而重载运算符。例如，+ 号应该表现得像数学加法；如果 a + b 成立，通常也应实现 b + a 以保持对称。

4.7 访问控制

核心逻辑：最小权限原则，统一声明顺序。
深度解释：
- 成员默认私有：保证数据封装。
- 声明顺序：public -> protected -> private。这是一种约定俗成的视觉惯例，让阅读者先看到接口，再看到实现细节。

5. 函数

5.1 输入输出参数顺序

核心逻辑：遵循“输入在前，输出在后”的约定。
深度解释：
- 输入参数：通常使用 const 引用（const T&）或值传递。
- 输出参数：通常为非 const 指针（T*），因为指针本身就暗示了该参数会被修改，且调用时需要传地址，这为调用方提供了清晰的视觉警告。
- 实操规则：如果函数签名中参数多达 5-6 个，且混杂了输入与输出，那么该函数的职责可能过重，应考虑重构。

5.2 函数长度

核心逻辑：“单一职责原则”的函数体现。
深度解释：
- 短小即美：倾向于编写 40 行以内的函数。如果函数很长，意味着它可能同时处理了多个逻辑，或者嵌套了过多的分支。
- 自动化重构：短函数极大提高了代码复用率，且更容易编写单元测试。如果一段逻辑被拆分成独立的短函数，调试时可以通过调用栈快速定位到具体的逻辑块。

5.3 重载与默认参数

核心逻辑：减少接口的认知负荷，防止隐藏的“行为多样性”。
深度解释：
- 谨慎重载：重载函数必须在语义上一致。如果两个重载版本完成的任务完全不同，应分别命名为 DoThis() 和 DoThat()，而不是 DoSomething(int) 和 DoSomething(string)。
- 禁止默认参数：
  - 原因：默认参数在编译期绑定。如果后续代码在调用链中发生了变化（如库升级），默认参数可能会引发意想不到的二进制兼容性问题（ABI 问题）。
  - 替代方案：使用函数重载或者建造者模式 (Builder Pattern) 来显式提供参数。

5.4 尾置返回类型

核心逻辑：仅在“非此不可”的场景下使用。
深度解释：
- 标准语法：传统 C++ 函数返回类型在前（如 int Func()）。
- 适用场景：
  1. 模板编程：当返回类型依赖于参数类型时，必须使用尾置返回（如 template <typename T, typename U> auto Add(T t, U u) -> decltype(t + u)）。
  2. Lambda 表达式：处理复杂的 Lambda 返回逻辑时，尾置语法能显著提高可读性。
- 建议：对于普通函数，请坚持使用传统语法，因为它更符合大多数 C++ 开发者的阅读习惯。

6. Google 特有规则与特性

6.1 资源与所有权管理

智能指针 (unique_ptr/shared_ptr) ：核心逻辑是所有权明确化。 unique_ptr 表示独占，shared_ptr 表示共享，严禁裸指针（raw pointer）跨越函数边界持有所有权。这从根源上杜绝了内存泄漏。
右值引用 ：主要用于避免大对象（如 std::vector 或 std::string）的不必要拷贝，通过移动语义提升性能。
异常与 noexcept：Android 系统中异常会导致运行时开销过大（栈展开），且 noexcept 能提示编译器进行优化，并帮助调用者在处理关键逻辑时明确其安全性。
友元：属于封装的“例外”，仅在逻辑紧密相连的类（如 Class A 与其对应的 A::Builder）之间使用，禁止滥用以防止类之间产生强耦合。

6.2 类型安全与编译优化

类型转换 (static_cast 等) ：C 风格转换（如 (int*)p）太危险且隐蔽，C++ 显式转换明确了转换意图（如 static_cast 是安全转换，reinterpret_cast 是不安全转换），便于 Code Review 审计。
定宽整数 (int32_t, uint64_t) ：在 Android 这种横跨 ARM/x86 架构的系统中，int 的长度是不确定的，强制使用定宽整数是保证跨平台 ABI 一致性的基石。
constexpr 系列：鼓励将逻辑从运行期迁移至编译期。这不仅能提升运行性能，还能在编译阶段通过 static_assert 捕获配置错误。

6.3 现代 C++ 语言特性

nullptr：完全替换 0 或 NULL。在 Android 等强类型要求高的环境下，nullptr 避免了在重载函数匹配中产生歧义。
auto 类型推导：原则是：若变量类型在上下文中显而易见，则用 auto；否则必须写明类型。 旨在提高代码可读性而非盲目追求简洁。
Lambda 表达式：是取代旧式“函数指针回调”的最佳选择，它能就地捕获变量，让局部逻辑编写极其紧凑。

6.4 避坑与约束 (防御性编程)

RTTI ：如 dynamic_cast 和 typeid。它们依赖于庞大的运行时类型支持，在 Android 底层代码中，使用 RTTI 通常意味着架构设计上有缺陷，应通过多态接口重构解决。
预处理器宏：宏没有作用域限制且容易产生副作用。在现代 C++ 中，大部分宏都可以用 constexpr 函数、inline 函数或 enum class 代替。
模板元编程 ：这是“专家级”特性。 过度使用模板会使错误日志变成“天书”，且极大增加编译时间。原则是：除非能带来不可替代的性能收益，否则拒绝过度设计。

7. 命名与注释

7.1 命名规范

核心原则：通过名称即刻区分实体的性质。

实体类型	命名格式	示例
文件命名	全小写 + 下划线	`my_feature_controller.cc`
类型命名	大驼峰 (PascalCase)	`class AudioBuffer`
变量命名	小写 + 下划线	`int packet_size;`
成员变量	小写 + 下划线 + 末尾下划线	`int packet_size_;`
常量命名	k + 大驼峰	`const int kMaxRetryCount = 5;`
函数命名	小驼峰 (camelCase)	`void processData();`
命名空间	全小写 (单数)	`namespace audio { ... }`
宏命名	全大写 + 下划线	`#define MAX_BUFFER_SIZE`

为什么要给成员变量加末尾下划线 (_) ：这是为了在代码中一目了然地识别出“这是类成员，还是局部变量”。例如，当看到 packet_size_ 时，无需查找定义就能确认它是一个成员属性。
为何常量用 k 前缀：这是 Google 的传统，通过 k 前缀明确区分普通的 const 变量和全局常量。

7.2 注释风格

核心原则：注释应解释“为什么 (Why)”和“约束 (Constraints)”，而非“是什么 (What)”。 代码本身已经解释了是什么，如果代码写得好，无需注释也能读懂；注释的价值在于解释代码背后的设计逻辑。

7.2.1 文件注释

每个文件顶部应有版权声明（通常是 Google 标准模板）和简短的模块功能说明。
如果文件涉及到底层硬件操作或复杂的算法，应在此处注明主要参考文档或算法来源。

7.2.2 类/函数注释

类注释：说明类的用途、线程安全约束（例如：“此类不是线程安全的，调用前需加锁”）。
函数注释：
- 功能说明：函数做了什么。
- 参数说明：输入输出参数的含义。
- 前提条件 ：调用前必须满足的条件（如“指针参数不能为 null”）。
- 所有权与生命周期：如果返回了一个指针，必须说明调用方是否拥有该指针的所有权（即是否需要手动 delete）。

7.2.3 实现注释

复杂逻辑：对于复杂算法、数学推导或特殊场景（如为了避开某个特定 Bug 而写的奇怪代码），必须写明理由。
TODO 注释：使用 TODO(username): 待办事项说明。这是一种非常有用的沟通工具，方便团队协作与进度追踪。

8. 格式

8.1 缩进与行列限制

缩进：一律使用 2 个空格（注意：禁止使用 Tab 键）。这在 Android 的嵌套结构（如多层嵌套的 if 或 lambda）中尤为重要，可以防止代码过早向右“溢出”。
最大行长度 ：每行不得超过 80 个字符。
- 理由：这不仅是为了在一个屏幕上并排对比两个代码文件，更是为了强迫开发者拆分过于复杂的逻辑。如果一行代码太长，说明该逻辑行数应该被重构，或者需要定义临时变量。

8.2 括号位置

K&R 风格 ：左大括号 { 紧跟在控制语句或类定义之后（不换行），右大括号 } 独占一行（除非是空的 if 或简单的闭包）。
强制大括号：即使 if、for 或 while 内部只有一行代码，也必须使用大括号 {}。这是防止悬挂 else 问题和后续维护中添加错误逻辑的最有效防御手段。

8.3 指针与引用

类型修饰符位置：& 和 * 修饰符应紧靠类型名，而不是变量名。
- 规范示例：const string& name，int* ptr。
- 理由：这明确了 & 和 * 是类型的一部分，而非变量名的一部分，符合 C++ 类型系统的语义。

8.4 循环与分支语句

空格规则：
- 关键字（if, for, while, switch）后必须有一个空格。
- 括号内部不需要额外空格（例如 if (condition) 而非 if ( condition )）。
Switch 语句：
- 每一个 case 块必须缩进。
- 如果逻辑较长，必须使用大括号 {} 包裹 case 内部逻辑。
- 每一个 case 或 default 结尾必须有 break 或 return（除非有明确的 [[fallthrough]] 注释）。

8.5 空格与空行

水平空格：
- 运算符（+, -, =, == 等）两侧均需加空格。
- 逗号之后必须加空格，之前禁止加空格。
垂直空格：
- 文件末尾必须保留一个换行符。
- 禁止在函数内部出现“大段”连续的空行（如超过两个），除非是为了在逻辑模块间进行有效的视觉分割。

9. 异常与例外

9.1 既有代码维护

核心逻辑：不因追求完美而破坏现有系统的稳定性。

深度解释：
- 渐进式重构：如果你在维护一个庞大的遗留项目（如早期的 Android 模块），要求立即将数万行代码全部重写为符合 C++20 和智能指针规范是不现实的。
- 豁免原则：
  - 最小改动原则：在修改遗留代码时，原则是“保持局部风格一致性”。如果周围的代码全是 new/delete 和裸指针，你强行植入智能指针可能会导致逻辑冲突或意想不到的内存生命周期问题。
  - 重构边界：只有在进行大规模模块重写或功能替换时，才必须完全遵循新规范。
- 风险提示：豁免并不等于“无视”。在维护遗留代码时，你应该尽量在新编写的代码路径上使用现代标准，同时通过封装的方式将现代代码与老旧代码隔离。

9.2 平台特性

核心逻辑：为特定平台的底层实现提供合法化接口。

深度解释：
- 为什么需要特殊规则：虽然 Android 基于 Linux 内核，但在某些极端场景下（如与系统驱动交互、底层图形处理、或者为了兼容 Windows 开发环境进行跨平台调试），可能会用到标准 C++ 以外的扩展。
- 合规操作：
  - 封装隔离：任何平台相关的代码（如特定的 Windows API 或 asm 汇编）都必须被严密地封装在独立的源文件或抽象层中。
  - 宏防护：使用明确的宏（如 #if defined(_WIN32)）进行隔离，严禁在业务逻辑中零散嵌入平台特性。
- Windows 开发者的特殊性：在 Android 工程中，偶尔需要调试代码在 Windows 模拟器或开发机上的表现。指南允许在开发阶段包含 Windows 专用头文件或库，但必须确保构建系统（Android.bp/CMake）能正确处理这些依赖，且不会污染最终部署到 Android 设备的二进制文件。