在 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 位。多使用 中的 、 等标准类型，确保安全。
  • 内存对齐与 Padding：不要假设结构体在所有平台上内存布局完全相同。只要涉及二进制数据传输，就必须显式定义序列化格式，拒绝侥幸心理。
• 为什么移植性至关重要？
  • 当 Android 推动指令集架构升级（如向纯 64 位系统迁移）时，忽视移植性的代码极易引发隐蔽的内存访问异常（SIGBUS/SIGSEGV），排查过程极其痛苦。

2. 头文件

2.1 自包含头文件

• 核心逻辑：头文件必须“开箱即用”。
• 深度解释：一个合格的 .h 文件，在包含完自身所需的所有依赖后，应能独立通过编译，即 g++ -c my_header.h 不报错。
• 为何重要：若头文件不自包含，调用方需先理清其内部依赖链条。一旦依赖关系变化，所有调用方都将受影响，形成“牵一发而动全身”的编译灾难。

2.1 #define 防御

• 核心逻辑：防止重复定义。
• 深度解释：在复杂项目中，一个头文件可能通过不同路径被多次 #include。若无防御机制，编译器遇到重复定义的类、函数或变量会直接报错。
• 规范化建议：使用“工程名+路径+文件名”的组合作为唯一标识符。
• 注意：#pragma once 虽常用，但 Google C++ 指南从可移植性角度推荐宏防御，因为 #pragma once 并非标准特性。

2.3 IWYU 原则

• 核心逻辑：“用什么包含什么”，杜绝隐式依赖。
• 深度解释：不能依赖头文件之间的传递包含关系。若 A.h 包含 B.h，你不能因引用 A.h 就直接在代码中使用 B.h 中的符号。
• 实操建议：
  • 若在 .cc 文件中使用了 std::vector，即使它已被某个已包含的头文件间接引用，也必须在 .cc 中显式添加 #include 。
  • 优点：删除冗余 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() 函数尚未运行时，程序已因相互依赖而崩溃。
  • 复杂对象：不要使用 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）。
• 深度解释：若不显式声明，编译器会生成默认复制/移动构造函数。但若类管理了资源（如文件句柄、原始指针），默认浅拷贝会引发重复析构，导致程序崩溃。
• 建议：若不需要拷贝，用 = 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 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)：在横跨 ARM/x86 架构的 Android 系统中，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 命名规范

核心原则：通过名字就能立刻区分实体的性质。

• 为何给成员变量加末尾下划线 (_)：旨在代码中一目了然地区分“类成员”与“局部变量”。例如看到 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）中，2 空格缩进尤为重要，可防止代码过早向右“溢出”。
• 最大行长度：每行不得超过 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 设备上的二进制文件。