From ab56670af9818d0a5bd628eb5c5dea6382f8de89 Mon Sep 17 00:00:00 2001 From: Karl Wiberg Date: Thu, 31 Jan 2019 02:34:39 +0100 Subject: [PATCH] Add a small README file for api/ Bug: none Change-Id: Ied90a30724c3b3230af4aa4ffa8d4ee5b617f8a6 Notry: true Reviewed-on: https://webrtc-review.googlesource.com/c/120605 Reviewed-by: Mirko Bonadei Commit-Queue: Karl Wiberg Cr-Commit-Position: refs/heads/master@{#26510} --- api/README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 api/README.md diff --git a/api/README.md b/api/README.md new file mode 100644 index 0000000000..4cc799362d --- /dev/null +++ b/api/README.md @@ -0,0 +1,24 @@ +# How to write code in the `api/` directory + +Mostly, just follow the regular [style guide](../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](../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.