WebRTC编码风格指南

WebRTC coding style guide

WebRTC编码风格指南

General advice

通用建议

Some older parts of the code violate the style guide in various ways. If making large changes to such code, consider first cleaning it up in a separate CL.

代码的一些旧部分以各种方式违反了样式指南。如果对此类代码进行了较大的更改，请考虑首先在单独的CL中对其进行清理。

C++

WebRTC follows the Chromium C++ style guide and the Google C++ style guide. In cases where they conflict, the Chromium style guide trumps the Google style guide, and the rules in this file trump them both.

​WebRTC遵循Chromium C++风格指南和Google C++风格指南。在它们冲突的情况下，Chromium风格的指南胜过Google风格的指南，而此文档中的规则则胜过两者。

C++ version

C++版本

WebRTC is written in C++17, but with some restrictions:

WebRTC是用C++17编写的，但有一些限制：

• We only allow the subset of C++17 (language and library) that is not banned by Chromium; see the list of banned C++ features in Chromium.
• ​我们只允许C++17（语言和库）中未被Chromium禁止的子集；请参阅Chromium中禁用的C++功能列表。
• We only allow the subset of C++17 that is also valid C++20; otherwise, users would not be able to compile WebRTC in C++20 mode.
• 我们只允许C++17的子集也是有效的C++20；否则，用户将无法在C++20模式下编译WebRTC。

Abseil

You may use a subset of the utilities provided by the Abseil library when writing WebRTC C++ code; see the instructions on how to use Abseil in WebRTC.

​在编写WebRTC C++代码时，可以使用Abseil库提供的实用程序的子集；请参阅有关如何在WebRTC中使用Abseil的说明。

.h and .cc files come in pairs

.h和.cc文件成对出现

.h and .cc files should come in pairs, with the same name (except for the file type suffix), in the same directory, in the same build target.

.h和.cc文件应该成对出现，具有相同的名称（文件类型后缀除外），位于相同的目录中，位于相同构建目标中。

• If a declaration in path/to/foo.h has a definition in some .cc file, it should be in path/to/foo.cc.
• 如果path/to/foo.h中的声明在某个.cc文件中有定义，那么它应该在path/to/foo.cc中。
• If a definition in path/to/foo.cc file has a declaration in some .h file, it should be in path/to/foo.h.
• 如果path/to/foo.cc文件中的定义在某个.h文件中有声明，那么它应该在path/to/foo.h中。
• Omit the .cc file if it would have been empty, but still list the .h file in a build target.
• 如果.cc文件为空，则省略该文件，但仍在生成目标中列出.h文件。
• Omit the .h file if it would have been empty. (This can happen with unit test .cc files, and with .cc files that define main.)
• 如果.h文件是空的，请省略它。（这可能发生在单元测试.cc文件和定义main的.cc文件中。）

See also the examples and exceptions on how to treat .h and .cpp files.

​另请参阅有关如何处理.h和.cpp文件的示例和例外情况。

This makes the source code easier to navigate and organize, and precludes some questionable build system practices such as having build targets that don't pull in definitions for everything they declare.

这使得源代码更容易导航和组织，并排除了一些有问题的构建系统实践，例如构建目标不为其声明的所有内容引入定义。

TODO comments

所有评论

Follow the Google styleguide for TODO comments. When referencing a WebRTC bug, prefer using the URL form (excluding the scheme part):

​按照谷歌风格指南获取TODO评论。当引用WebRTC错误时，更喜欢使用URL表单（不包括方案部分）：

// TODO(bugs.webrtc.org/12345): Delete the hack when blocking bugs are resolved.

The short form used in commit messages, e.g. webrtc:12345, is discouraged.

不鼓励在提交消息中使用缩写形式，例如webrtc:12345。

Deprecation

不推荐

Annotate the declarations of deprecated functions and classes with the [[deprecated]] attribute to cause an error when they‘re used inside WebRTC and a compiler warning when they’re used by dependant projects. Like so:

​使用[[deprecated]]属性注释不推荐使用的函数和类的声明，当它们在WebRTC中使用时会导致错误，当它们被依赖项目使用时会引起编译器警告。就像这样：

[[deprecated("bugs.webrtc.org/12345")]]
std::pony PonyPlz(const std::pony_spec& ps);

NOTE 1: The annotation goes on the declaration in the .h file, not the definition in the .cc file!

注1：注释在.h文件中的声明上，而不是在.cc文件中的定义上！

NOTE 2: In order to have unit tests that use the deprecated function without getting errors, do something like this:

注2：为了使单元测试使用不推荐使用的函数而不会出现错误，请执行以下操作：

std::pony DEPRECATED_PonyPlz(const std::pony_spec& ps);
[[deprecated("bugs.webrtc.org/12345")]]
inline std::pony PonyPlz(const std::pony_spec& ps) {
  return DEPRECATED_PonyPlz(ps);
}

In other words, rename the existing function, and provide an inline wrapper using the original name that calls it. That way, callers who are willing to call it using the DEPRECATED_-prefixed name don't get the warning.

换句话说，重命名现有函数，并使用调用它的原始名称提供内联包装。这样，愿意使用DEPRECATED_前缀名称调用它的调用方就不会收到警告。

NOTE 3: Occasionally, with long descriptions, git cl format will do the wrong thing with the attribute. In that case, you can use the ABSL_DEPRECATED macro, which is formatted in a more readable way.

​注3：偶尔，对于长描述，git-cl格式会对属性做错误的处理。在这种情况下，可以使用ABSL_DEPRECATED宏，该宏的格式更可读。

ArrayView

阵列视图

When passing an array of values to a function, use rtc::ArrayView whenever possible—that is, whenever you‘re not passing ownership of the array, and don’t allow the callee to change the array size.

将值数组传递给函数时，请尽可能使用rtc::ArrayView，也就是说，只要不传递数组的所有权，并且不允许被调用者更改数组大小。

For example,

例如

instead of	use
const std::vector<T>&	ArrayView<const T>
const T* ptr, size_t num_elements	ArrayView<const T>
T* ptr, size_t num_elements	ArrayView<T>

See the source code for rtc::ArrayView for more detailed docs.

​有关更多详细文档，请参阅rtc::ArrayView的源代码。

sigslot

信号槽

SIGSLOT IS DEPRECATED.

信号槽已弃用。

Prefer webrtc::CallbackList, and manage thread safety yourself.

更喜欢webrtc::CallbackList，并自己管理线程安全。

Smart pointers

智能指针

The following smart pointer types are recommended:

建议使用以下智能指针类型：

• std::unique_ptr for all singly-owned objects
• std::unique_ptr用于所有单独拥有的对象
• rtc::scoped_refptr for all objects with shared ownership
• 具有共享所有权的所有对象的rtc::scoped_refptr

Use of std::shared_ptr is not permitted. It is banned in the Chromium style guide (overriding the Google style guide). See the list of banned C++ library features in Chromium for more information.

​不允许使用std::shared_ptr。Chromium风格的指南中禁止使用它（凌驾于谷歌风格的指南之上）。有关更多信息，请参阅Chromium中禁用的C++库功能列表。

In most cases, one will want to explicitly control lifetimes, and therefore use std::unique_ptr, but in some cases, for instance where references have to exist both from the API users and internally, with no way to invalidate pointers held by the API user, rtc::scoped_refptr can be appropriate.

在大多数情况下，人们会希望显式地控制生存期，因此使用std::unique_ptr，但在某些情况下，例如，在必须存在来自API用户和内部的引用的情况下，无法使API用户持有的指针无效，rtc::scoped_refptr可能是合适的。

std::bind

Don't use std::bind—there are pitfalls, and lambdas are almost as succinct and already familiar to modern C++ programmers.

不要使用std::bind——这是有陷阱的，lambdas几乎同样简洁，而且现代C++程序员已经很熟悉了。

std::function

std::function is allowed, but remember that it's not the right tool for every occasion. Prefer to use interfaces when that makes sense, and consider rtc::FunctionView for cases where the callee will not save the function object.

std::function是允许的，但请记住，它并不是适合所有场合的工具。在有意义的情况下，更喜欢使用接口，对于被调用者不保存函数对象的情况，请考虑rtc::FunctionView。

Forward declarations

向前声明

WebRTC follows the Google C++ style guide on forward declarations. In summary: avoid using forward declarations where possible; just #include the headers you need.

​WebRTC遵循Google C++风格的向前声明指南。总之：尽可能避免使用向前声明；只需#include您需要的标题。

RTTI and dynamic_cast

The Google style guide permits the use of dynamic_cast.

​谷歌风格指南允许使用dynamic_cast。

However, WebRTC does not permit it. WebRTC (and Chrome) is compiled with the -fno-rtti flag, and the overhead of enabling RTTI it is on the order of 220 Kbytes (for Android Arm64).

然而，WebRTC不允许这样做。WebRTC（和Chrome）是用-fno-rtti标志编译的，启用rtti的开销大约为220 KB（对于Android Arm64）。

Use static_cast and take your own steps to ensure type safety.

使用static_cast并采取自己的步骤来确保类型安全。

C

There's a substantial chunk of legacy C code in WebRTC, and a lot of it is old enough that it violates the parts of the C++ style guide that also applies to C (naming etc.) for the simple reason that it pre-dates the use of the current C++ style guide for this code base. If making large changes to C code, consider converting the whole thing to C++ first.

WebRTC中有大量的遗留C代码，其中很多已经足够旧了，它违反了C++风格指南中同样适用于C（命名等）的部分，原因很简单，因为它早于当前C++风格指南对该代码库的使用。如果对C代码进行了较大的更改，请考虑先将整个代码转换为C++。

Java

WebRTC follows the Google Java style guide.

​WebRTC遵循Google Java风格指南。

Objective-C and Objective-C++

WebRTC follows the Chromium Objective-C and Objective-C++ style guide.

​WebRTC遵循Chromium Objective-C和Objective-C++风格指南。

Python

WebRTC follows Chromium's Python style.

​WebRTC遵循Chromium的Python风格。

Build files

构建文件

The WebRTC build files are written in GN, and we follow the GN style guide. Additionally, there are some WebRTC-specific rules below; in case of conflict, they trump the Chromium style guide.

​WebRTC构建文件是用GN编写的，我们遵循GN样式指南。此外，下面还有一些特定于WebRTC的规则；在发生冲突的情况下，它们胜过Chromium风格的指南。

WebRTC-specific GN templates

WebRTC特定的GN模板

As shown in the table below, for library targets (source_set and static_library), you should default on using rtc_library (which abstracts away the complexity of using the correct target type for Chromium component builds).

如下表所示，对于库目标（source_set和static_library），应该默认使用rtc_library（它抽象了为Chromium组件构建使用正确目标类型的复杂性）。

The general rule is for library targets is:

库目标的一般规则是：

1.Use rtc_library.

1.使用rtc_library。

2.If the library is a header only target use rtc_source_set.

2.如果库是仅标头的目标，请使用rtc_source_set。

3.If you really need to generate a static library, use rtc_static_library (same for shared libraries, in such case use rtc_shared_library).

3.如果您真的需要生成一个静态库，请使用rtc_static_library（对于共享库也是如此，在这种情况下使用rtc_shared_library）。

To ensure that all our GN targets are built with the same configuration, only use the following GN templates.

​为了确保我们的所有GN目标都是使用相同的配置构建的，请仅使用以下GN模板。

instead of	use
executable	rtc_executable
shared_library	rtc_shared_library
source_set	rtc_source_set (only for header only libraries, for everything else use rtc_library
static_library	rtc_static_library (use rtc_library unless you really need rtc_static_library
test	rtc_test

Target visibility and the native API

目标可见性和本地API

The WebRTC-specific GN templates declare build targets whose default visibility allows all other targets in the WebRTC tree (and no targets outside the tree) to depend on them.

​WebRTC特定的GN模板声明构建目标，其默认可见性允许WebRTC树中的所有其他目标（树外没有目标）依赖于它们。

Prefer to restrict the visibility if possible:

如果可能的话，最好限制可见度：

• If a target is used by only one or a tiny number of other targets, prefer to list them explicitly: visibility = [ ":foo", ":bar" ]
• 如果一个目标只被一个或极少数其他目标使用，则更喜欢明确列出它们：visibility = [ ":foo", ":bar" ]
• If a target is used only by targets in the same BUILD.gn file: visibility = [ ":*" ].
• 如果目标仅由同一BUILD.gn文件中的目标使用：visibility=[“：*”]。

Setting visibility = [ "*" ] means that targets outside the WebRTC tree can depend on this target; use this only for build targets whose headers are part of the native WebRTC API.

​设置visibility = [ "*" ]意味着WebRTC树之外的目标可以依赖于此目标；仅将其用于其标头是本地WebRTC API的一部分的构建目标。

Conditional compilation with the C preprocessor

使用C预处理器进行条件编译

Avoid using the C preprocessor to conditionally enable or disable pieces of code. But if you can't avoid it, introduce a GN variable, and then set a preprocessor constant to either 0 or 1 in the build targets that need it:

避免使用C预处理器来有条件地启用或禁用代码段。但如果无法避免，请引入GN变量，然后在需要它的构建目标中将预处理器常量设置为0或1：

if (apm_debug_dump) {
  defines = [ "WEBRTC_APM_DEBUG_DUMP=1" ]
} else {
  defines = [ "WEBRTC_APM_DEBUG_DUMP=0" ]
}

In the C, C++, or Objective-C files, use #if when testing the flag, not #ifdef or #if defined():

在C、C++或Objective-C文件中，测试标志时使用#if，而不是#ifdef或#if defined（）：

#if WEBRTC_APM_DEBUG_DUMP
// One way.
#else
// Or another.
#endif

When combined with the -Wundef compiler option, this produces compile time warnings if preprocessor symbols are misspelled, or used without corresponding build rules to set them.

当与-Wundef编译器选项结合使用时，如果预处理器符号拼写错误，或者使用时没有相应的生成规则来设置它们，则会产生编译时警告。