e1d464ec7b
The default style of the L2 and L3 headers are too similar, making it difficult to see which is which. BUG=none NOTRY=true Change-Id: I0deede2ad5766db9b63baa48be8e4da4aba784ca Reviewed-on: https://chromium-review.googlesource.com/657697 Commit-Queue: Karl Wiberg <kwiberg@webrtc.org> Reviewed-by: Danil Chapovalov <danilchap@webrtc.org> Cr-Commit-Position: refs/heads/master@{#19759}
125 lines
4.1 KiB
Markdown
125 lines
4.1 KiB
Markdown
# WebRTC coding style guide
|
|
|
|
## **General advice**
|
|
|
|
Some older parts of the code violate the style guide in various ways.
|
|
|
|
* If making small changes to such code, follow the style guide when
|
|
it’s reasonable to do so, but in matters of formatting etc., it is
|
|
often better to be consistent with the surrounding code.
|
|
* If making large changes to such code, consider first cleaning it up
|
|
in a separate CL.
|
|
|
|
## **C++**
|
|
|
|
WebRTC follows the [Chromium][chr-style] and [Google][goog-style] C++
|
|
style guides. In cases where they conflict, the Chromium style guide
|
|
trumps the Google style guide, and the rules in this file trump them
|
|
both.
|
|
|
|
[chr-style]: https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++.md
|
|
[goog-style]: https://google.github.io/styleguide/cppguide.html
|
|
|
|
### 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.
|
|
|
|
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](webrtc/api/array_view.h) for more detailed docs.
|
|
|
|
## **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 small changes to C code, mimic the style of the
|
|
surrounding code.
|
|
* If making large changes to C code, consider converting the whole
|
|
thing to C++ first.
|
|
|
|
## **Java**
|
|
|
|
WebRTC follows the [Google Java style guide][goog-java-style].
|
|
|
|
[goog-java-style]: https://google.github.io/styleguide/javaguide.html
|
|
|
|
## **Objective-C and Objective-C++**
|
|
|
|
WebRTC follows the
|
|
[Chromium Objective-C and Objective-C++ style guide][chr-objc-style].
|
|
|
|
[chr-objc-style]: https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/objective-c/objective-c.md
|
|
|
|
## **Python**
|
|
|
|
WebRTC follows [Chromium’s Python style][chr-py-style].
|
|
|
|
[chr-py-style]: https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/styleguide.md#python
|
|
|
|
## **Build files**
|
|
|
|
The WebRTC build files are written in [GN][gn], and we follow
|
|
the [Chromium GN style guide][chr-gn-style]. Additionally, there are
|
|
some WebRTC-specific rules below; in case of conflict, they trump the
|
|
Chromium style guide.
|
|
|
|
[gn]: https://chromium.googlesource.com/chromium/src/tools/gn/
|
|
[chr-gn-style]: https://chromium.googlesource.com/chromium/src/tools/gn/+/HEAD/docs/style_guide.md
|
|
|
|
### WebRTC-specific GN templates
|
|
|
|
Use the following [GN templates][gn-templ] to ensure that all
|
|
our [targets][gn-target] are built with the same configuration:
|
|
|
|
instead of | use
|
|
-----------------|---------------------
|
|
`executable` | `rtc_executable`
|
|
`shared_library` | `rtc_shared_library`
|
|
`source_set` | `rtc_source_set`
|
|
`static_library` | `rtc_static_library`
|
|
`test` | `rtc_test`
|
|
|
|
[gn-templ]: https://chromium.googlesource.com/chromium/src/tools/gn/+/HEAD/docs/language.md#Templates
|
|
[gn-target]: https://chromium.googlesource.com/chromium/src/tools/gn/+/HEAD/docs/language.md#Targets
|
|
|
|
### Conditional compilation with the C preprocessor
|
|
|
|
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:
|
|
|
|
```
|
|
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()`:
|
|
|
|
```
|
|
#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.
|