Discourage structs in api
Structs make api harder to evolve:
deprecated unused properties,
change how data is represented.
Classes with accessors allow more graduated and safer api evolution.
Bug: None
Change-Id: I8ebd5e072d51cf7f5800666cfdac523d0f9a937f
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/317520
Reviewed-by: Harald Alvestrand <hta@webrtc.org>
Commit-Queue: Danil Chapovalov <danilchap@webrtc.org>
Cr-Commit-Position: refs/heads/main@{#40714}
diff --git a/api/README.md b/api/README.md
index 7153cb5..cf6d73a 100644
--- a/api/README.md
+++ b/api/README.md
@@ -13,8 +13,9 @@
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.
-That is, the preferred way for `api/` code to access non-`api/` code is to call
+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.
@@ -25,3 +26,12 @@
`.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.