diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-19 00:47:55 +0000 |
commit | 26a029d407be480d791972afb5975cf62c9360a6 (patch) | |
tree | f435a8308119effd964b339f76abb83a57c29483 /third_party/libwebrtc/api/README.md | |
parent | Initial commit. (diff) | |
download | firefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz firefox-26a029d407be480d791972afb5975cf62c9360a6.zip |
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'third_party/libwebrtc/api/README.md')
-rw-r--r-- | third_party/libwebrtc/api/README.md | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/third_party/libwebrtc/api/README.md b/third_party/libwebrtc/api/README.md new file mode 100644 index 0000000000..cf6d73a855 --- /dev/null +++ b/third_party/libwebrtc/api/README.md @@ -0,0 +1,37 @@ +<!-- go/cmark --> +<!--* freshness: {owner: 'hta' reviewed: '2021-01-01'} *--> + +# 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/`. +* Avoid structs in api, prefer classes. + +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. + +Avoid defining api with structs as it makes harder for the api to evolve. +Your struct may gain invariant, or change how it represents data. +Evolving struct from the api is particular challenging as it is designed to be +used in other code bases and thus needs to be updated independetly from its usage. +Class with accessors and setters makes such migration safer. +See [Google C++ style guide](https://google.github.io/styleguide/cppguide.html#Structs_vs._Classes) for more. + +If you need to evolve existent struct in api, prefer first to convert it into a class. |