46f5c11e4f
No-Try: true Bug: None Change-Id: I45c3e515f6e446f8982333869d8ad2c6ae15978d Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/218347 Reviewed-by: Harald Alvestrand <hta@webrtc.org> Reviewed-by: Artem Titov <titovartem@webrtc.org> Commit-Queue: Danil Chapovalov <danilchap@webrtc.org> Cr-Commit-Position: refs/heads/master@{#34004}
25 lines
1.2 KiB
Markdown
25 lines
1.2 KiB
Markdown
# How to write code in the `api/` directory
|
|
|
|
Mostly, just follow the regular [style guide](../g3doc/style-guide.md), but:
|
|
|
|
* Note that `api/` code is not exempt from the “`.h` and `.cc` files come in
|
|
pairs” rule, so if you declare something in `api/path/to/foo.h`, it should be
|
|
defined in `api/path/to/foo.cc`.
|
|
* Headers in `api/` should, if possible, not `#include` headers outside `api/`.
|
|
It’s not always possible to avoid this, but be aware that it adds to a small
|
|
mountain of technical debt that we’re trying to shrink.
|
|
* `.cc` files in `api/`, on the other hand, are free to `#include` headers
|
|
outside `api/`.
|
|
|
|
That is, the preferred way for `api/` code to access non-`api/` code is to call
|
|
it from a `.cc` file, so that users of our API headers won’t transitively
|
|
`#include` non-public headers.
|
|
|
|
For headers in `api/` that need to refer to non-public types, forward
|
|
declarations are often a lesser evil than including non-public header files. The
|
|
usual [rules](../g3doc/style-guide.md#forward-declarations) still apply, though.
|
|
|
|
`.cc` files in `api/` should preferably be kept reasonably small. If a
|
|
substantial implementation is needed, consider putting it with our non-public
|
|
code, and just call it from the `api/` `.cc` file.
|