Document an includes style, apply to z_demo.c and z_play.c (#2803)

* Document an includes style, apply to z_demo.c and z_play.c

* "reverse" style includes

* bss

* clarify what a "main header" is

* Update docs/includes.md

Co-authored-by: Tharo <tharo10600@gmail.com>

* Update docs/includes.md

---------

Co-authored-by: Tharo <tharo10600@gmail.com>

1 files changed, 62 insertions, 0 deletions

diff --git a/docs/includes.md b/docs/includes.md
new file mode 100644
index 000000000..50674627f
--- /dev/null
+++ b/docs/includes.md
@@ -0,0 +1,62 @@
+# Includes Style Guide
+
+## Include what you use
+
+We go by "include what you use", which basically means that for any symbol used by a .c file, the .h where that symbol is from must be included.
+
+A tool exists to help with this: `apt install iwyu`.
+
+This tool (and clangd) understands IWYU pragmas: we currently only make use of `IWYU pragma: export` and `IWYU pragma: begin_exports`/`IWYU pragma: end_exports`.
+
+For further details see https://github.com/include-what-you-use/include-what-you-use
+
+## Includes ordering
+
+The include should be ordered like this and sorted alphabetically within each group:
+
+- main header(s) for the system/overlay. That is, the .h file(s) that declare what the .c defines (functions, globals).
+- `versions.h` if needed
+- remaining includes not in this list
+- assets
+- `libc64/*.h`
+- `libu64/*.h`
+- `ultra64.h` if needed
+- libc (files from `include/libc`)
+
+This minimizes the chance for headers to not be self-contained.
+
+There should be no empty line between groups, except:
+
+- after the main .h include(s)
+- before and after assets includes if any
+- in-between assets includes, as needed
+
+## Angle brackets vs quotes
+
+Use angle brackets for libc includes (files from `include/libc`), and quotes for everything else.
+
+Example:
+
+```c
+#include "actor.h"
+#include <stddef.h>
+```
+
+## Conditional includes
+
+Some header files should be conditionally included, for example:
+
+```c
+#if PLATFORM_N64
+#include "n64dd.h"
+#endif
+```
+
+This should be done when a .h does not make sense to be included for all versions, for example because it provides symbols that a version doesn't even link (include in the spec).
+
+A list of such files is:
+
+- `cic6105.h` behind `PLATFORM_N64`
+- `inflate.h` behind `PLATFORM_IQUE`
+- `n64dd.h` behind `PLATFORM_N64`
+- `yaz0.h` behind `!PLATFORM_IQUE`