Google 开源项目风格指南 (中文版)
概述
本指南是由国内程序员翻译维护的 Google 开源项目风格指南中文版，涵盖 C++、Objective-C、Python、JSON、Shell 和 JavaScript 六种语言的编程规范。指南不仅列出规则，更解释背景 rationale，帮助开发者理解为何如此设计。
目录结构
- 第1章：Google 开源项目风格指南 (中文版) 总览
- 第2章：C++ 风格指南
- 第3章：Objective-C 风格指南
- 第4章：Python 风格指南
- 第5章：Shell 风格指南
- 第6章：Javascript 风格指南
关键要点（以 C++ 为例）
头文件
- 头文件应做到自包含（self-contained），除非用于纯文本插入（.inc）。
- 使用
#define保护，命名格式：<PROJECT>_<PATH>_<FILE>_H_。 - 尽量避免前置声明，除非必要；前置声明可能隐藏依赖并导致编译时问题。
- 内联函数仅限于体积小（≤10 行）的函数，避免滥用导致代码膨胀。
作用域
- 鼓励在 .cc 文件中使用匿名命名空间或
static以避免全局命名空间污染。 - 禁止在头文件中使用命名空间别名（除非显式标记）。
- 禁止在
std命名空间中声明任何内容。
类
- 构造函数中不应调用虚函数，也不应尝试报告非致命错误；考虑使用 Init() 方法或工厂函数。
- 单参数构造函数和转换运算符应显式声明
explicit，以防止隐式类型转换。 - 复制构造函数和复制赋值运算符应声明为
delete或私有，以防止不希望的复制。
其他语言要点概览
- Objective-C：类似 C++ 的命名空间与作用域规则，使用前缀避免命名冲突。
- Python：遵循 PEP 8，强调一致性和可读性；使用 4 空格缩进；模块、类、函数命名约定。
- Shell：使用 POSIX 兼容的写法；变量使用下划线；错误处理采用
set -euo pipefail。 - JavaScript：使用 JSDoc 进行类型注释；采用单引号字符串；避免
with和eval；使用goog.scope缩短命名空间。
应用建议
- 在项目初期采纳本指南，可通过配置编辑器插件（如 clang-format, yapf, eslint）自动检查。
- 进行代码审查时，重点检查头文件的自包含性、命名空间使用及内联函数的合理性。
- 指南中的“规则特例”章节提供了何时可以偏离规则的指导，保持灵活性。
与其他知识的关联
- 与《Effective C++》中的条款（如条款 30：使用
explicit防止隐式转换）相呼应。 - 与 Google 的开源项目实际代码库（如 Chromium, Protobuf）中的风格保持一致。
- 对于内部项目，可将本指南作为基础，结合团队实际情况进行裁剪。
行动点
- 将本指南的 C++ 章节转化为项目的
.clang-format配置。 - 在团队 Wiki 中链接此指南，并标记为必读材料。
- 下次代码审查时，重点检查头文件是否使用了
#define保护及前置声明的合理性。