| Karl Wiberg | ab56670 | 2019-01-31 01:34:39 | [diff] [blame] | 1 | # How to write code in the `api/` directory |
| 2 | |
| Danil Chapovalov | 46f5c11 | 2021-05-12 12:05:48 | [diff] [blame] | 3 | Mostly, just follow the regular [style guide](../g3doc/style-guide.md), but: |
| Karl Wiberg | ab56670 | 2019-01-31 01:34:39 | [diff] [blame] | 4 | |
| 5 | * Note that `api/` code is not exempt from the “`.h` and `.cc` files come in |
| 6 | pairs” rule, so if you declare something in `api/path/to/foo.h`, it should be |
| 7 | defined in `api/path/to/foo.cc`. |
| 8 | * Headers in `api/` should, if possible, not `#include` headers outside `api/`. |
| 9 | It’s not always possible to avoid this, but be aware that it adds to a small |
| 10 | mountain of technical debt that we’re trying to shrink. |
| 11 | * `.cc` files in `api/`, on the other hand, are free to `#include` headers |
| 12 | outside `api/`. |
| 13 | |
| 14 | That is, the preferred way for `api/` code to access non-`api/` code is to call |
| 15 | it from a `.cc` file, so that users of our API headers won’t transitively |
| 16 | `#include` non-public headers. |
| 17 | |
| 18 | For headers in `api/` that need to refer to non-public types, forward |
| 19 | declarations are often a lesser evil than including non-public header files. The |
| Danil Chapovalov | 46f5c11 | 2021-05-12 12:05:48 | [diff] [blame] | 20 | usual [rules](../g3doc/style-guide.md#forward-declarations) still apply, though. |
| Karl Wiberg | ab56670 | 2019-01-31 01:34:39 | [diff] [blame] | 21 | |
| 22 | `.cc` files in `api/` should preferably be kept reasonably small. If a |
| 23 | substantial implementation is needed, consider putting it with our non-public |
| 24 | code, and just call it from the `api/` `.cc` file. |
