1# How to write code in the `api/` directory 2 3Mostly, just follow the regular [style guide](../style-guide.md), but: 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 14That is, the preferred way for `api/` code to access non-`api/` code is to call 15it from a `.cc` file, so that users of our API headers won’t transitively 16`#include` non-public headers. 17 18For headers in `api/` that need to refer to non-public types, forward 19declarations are often a lesser evil than including non-public header files. The 20usual [rules](../style-guide.md#forward-declarations) still apply, though. 21 22`.cc` files in `api/` should preferably be kept reasonably small. If a 23substantial implementation is needed, consider putting it with our non-public 24code, and just call it from the `api/` `.cc` file. 25