Fuchsia 项目遵循公开的 Google C++ 样式指南,但有一些例外情况。
使用 clang-format 是一种很好的做法,因为它可以确保您的代码符合样式指南。Gerrit 中的 Tricium 检查还会使用 Clang 格式作为非门控 linter。不过,您仍然可以手动设置代码格式,只要代码符合这些准则即可。
紫红色专用样式
TODO 注释
Google C++ 样式指南要求在 TODO 注释中引用 bug 编号。在 Fuchsia 上,以 TODO(https://fxbug.dev/42074368)
格式完成上述操作。
编译标志
请勿添加 -Wall
或 -Wextra
。
source_set("my_sources") {
...
cflags = [
# Don't do this!
"-Wall",
]
}
此标志已添加到 build 的集中位置,后跟可在全局范围内抑制某些警告的其他标志。
偶尔会向上游添加新的编译器警告。为了推出最新的编译器,当我们处理大量关于修复整个代码库中此警告实例的积压时,全局维护人员可能会选择在一个集中位置暂时抑制新引入的警告。如果您的项目使用 -Wall
,则可能会因 Clang 滚动而中断。
您可以随意启用/停用未进行全局设置的特定警告。如果稍后以符合您自己的偏好设置的方式在全局范围内设置这些警告,则最好移除所有本地替换值。
source_set("my_sources") {
...
cflags = [
# We don't want any write-only params/vars in our code.
# TODO(https://fxbug.dev/42133916): delete the below when these warnings are
# enabled globally.
"-Wunused-but-set-parameter",
"-Wunused-but-set-variable",
]
}
异常
行长
Fuchsia 使用 100 列而不是 80 列。
大括号
如果块的内容多于一行,请始终使用大括号 { }
。您需要注意这一点,因为 Clang 格式不知道要添加这些组件。
// Don't do this.
while (!done)
doSomethingWithAReallyLongLine(
wrapped_arg);
// Correct.
while (!done) {
doSomethingWithAReallyLongLine(
wrapped_arg);
}
条件和循环
不要在圆括号内使用空格(Google 样式指南不建议这样做,但允许这样做)。
不要将单行形式用于简短的条件语句和循环(Google 风格指南允许两种形式):
// Don't do this:
if (x == kFoo) return new Foo();
// Correct.
if (x == kFoo) {
return new Foo;
}
命名空间名称
- 禁止使用嵌套命名空间,但以下情况除外:
internal
(如果需要,用于隐藏模板化代码的实现详情)- 由 FIDL 编译器生成的代码
- 禁止使用以下顶级命名空间:
internal
fuchsia
(FIDL 编译器生成的代码除外)
- IDK 库中的命名空间必须尽可能简短。后续文档将明确列出允许的命名空间;与此同时,引入新的命名空间时应深思熟虑。
- 还应选择非 IDK 库中的命名空间,以降低冲突风险。非常宽泛的名词(例如
media
)的调用。
理由:本周提示:命名空间命名
包含
如果要包含的头文件是系统头文件、全局头文件或库头文件(如需了解精确定义,请参阅为 C/C++ 对象命名),请使用
<angle brackets>
和头文件的全名。在 Google C++ 样式指南中,这些头文件被视为“C 库头文件”:#include <zircon/syscalls.h> // System header #include <fuchsia/io/cpp/fidl.h> // Global header #include <lib/fdio/fd.h> // Library header
如果要包含的头文件是实现头文件,请使用
"quotes"
并使用从源代码树的根目录到该头文件的完整路径。按照 Google C++ 样式指南的目的,这些头文件被视为“您的项目的头文件”:#include "src/ui/scenic/bin/app.h" // Implementation header
可以使用相对根级路径(例如
#include "third_party/skia/include/core/SkPaint.h"
)或使用其规范化标头名称(例如#include <gtest/gtest.h>
)来添加第三方标头。