update contributing.md and style.md (#76)

* initial commit

* fixed wording

* more fixed wording

* review

1 files changed, 27 insertions, 15 deletions

diff --git a/docs/STYLE.md b/docs/STYLE.md
index a3bd6c6..15c3d58 100644
--- a/docs/STYLE.md
+++ b/docs/STYLE.md
@@ -5,6 +5,8 @@ In general, documented files are a good place to look to understand this project
 ## Original Names
 A large amount of the original names for functions, data, bss, and objects are present in the linker map files found in Doubutsu no Mori +, Animal Crossing, and Doubutsu no Mori e+. Because of this, this project aims to use the original names if known. These take priority over all code style guidelines.
 
+These .map files can be found pinned in the `#af-decomp` channel in our discord.
+
 Some functions were present in DnM and removed in DnM+. You can choose a name for these, but they should match the same style as the other functions in the file, and be accompanied with a comment  
 ```c
 // Original name unknown.
@@ -12,6 +14,8 @@ Some functions were present in DnM and removed in DnM+. You can choose a name fo
 
 Notably local variables, structs, struct members, enums, and macros are not in the linker map files. Sometimes these can be deduced from function names, debug strings, or Ocarina of Time / Majora's Mask. These original names should be used as well.
 
+If you are simply decompiling a file and are not entirely sure what the function's name should be, or what a struct should be called, It is preferable to leave functions unnamed, or use unk_struct_XXX for structs, unk_XXX for struct members, etc. If something is named incorrectly it can be confusing to correct in the future.
+
 ## Types
 
 Use the types from `ultratypes.h`, not the standard C types: i.e. `u8`,`s8`,`s16`,`u16`,`s32`,`u32`,`f32` rather than `char`, `short`, `int`, `float` and their `signed`/`unsigned` varieties.
@@ -114,22 +118,23 @@ Floats usually need an `f` on the end to match, or IDO will use doubles. Our flo
 - Use `sizeof` or `ARRAY_COUNT`/`ARRAY_COUNTU` where it makes sense, e.g. in loops that are using an array.
 - clang-format sometimes does weird things to array formatting. Experiment with and without a comma after the last element and see which looks better.
 
-## Play2
+## game_play2
+
+In some particular instances, IDO requires the function argument `game_play` to be cast to a second variable of the same type to match. In these particular instances, the function argument should be renamed to `game_play2` and than this `game_play2` just assigned to a stack variable called `game_play`. This cast should occur before the actor `THIS` cast is made. For example:
 
-In some particular instances, IDO requires the function argument `game_play` to be cast to a second variable of the same type to match. In these particular instances, the function argument should be renamed to `play2` and than this `play2` just assigned to a stack variable called `game_play`. This cast should occur before the actor `THIS` cast is made. For example in `z_en_firefly.c`
 ```c
-void EnFirefly_Update(Actor* thisx, Game_Play* play2) {
-    Game_Play* game_play = play2;
-    EnFirefly* this = THIS;
+void aTOU_actor_init(Actor* thisx, Game_Play* game_play2) {
+    Game_Play* game_play = game_play2;
+    Structure* this = THIS;
 ```
 
-In other places the cast is actually not explicitly needed, but a stack `pad` variable is still needed. For this there should just be a stack variable called `pad` of type `s32` before the actor `THIS` cast. For example in `z_bg_goron_oyu`
+In other places the cast is actually not explicitly needed, but a stack `pad` variable is still needed. For this there should just be a stack variable called `pad` of type `s32` before the actor `THIS` cast. For example:
 
 ```c
-void BgGoronOyu_Init(Actor* thisx, Game_Play* game_play) {
+void aTOU_actor_ct(Actor* thisx, Game_Play* game_play) {
     s32 pad;
-    BgGoronOyu* this = THIS;
-    CollisionHeader* colHeader = NULL;
+    Structure* this = THIS;
+    s32 type = (common_data.time.season == WINTER);
 ```
 
 ## Documentation and Comments
@@ -165,20 +170,27 @@ We use comments for:
 - If something in a function is strange, or unintuitive, do leave a comment explaining what's going on. We use `//` for this.
 - We also use `//` for temporary comments above a function. Feel free to use `TODO:` in these if appropriate.
 - A bug should be commented with an `//! @bug Bug description` above the code that causes the bug.
+- For "fake matches", awful code that exists only to make the function's assembly match, mark these with `//! FAKE`
 
 ## What goes where
 
-This section mostly applies to actors.
-
 ### Functions
 
-All functions should go in the main C file in the same order as the assembly (the latter is required to match anyway). (We may make exceptions for particularly large files with a particular organisational structure, but we ask that you check on Discord first before doing this)
+All functions should go in the main C file in the same order as the assembly (the latter is required to match anyway). (We may make exceptions for particularly large files with a particular organizational structure, but we ask that you check on Discord first before doing this)
+
+### Prototypes
+
+Actors:
+- Only make prototypes that are necessary. Because actors are usually self contained, prototypes should be placed in the main C file, unless they are used by something outside of the file, where they should be placed in the header.
+
+Other files (boot, code, etc):
+- Prototypes should be placed in the header. You can omit functions that shouldn't be used outside the file.
 
 ### Data
 
 - If in doubt, leave all the data at the top of the file. Reviewers will decide for you.
 - Data must go in the same order as in the assembly files, but is only constrained by other data, not functions or rodata.
-- Some data has to be inline static to match. Generally it's better to not use `static` on data outside funtions until the file is matching, since `static` data is left out of the mapfile and this makes debugging harder.
+- Do not use `static` on data outside functions, since `static` data is left out of the mapfile and this makes debugging harder. Only use static when necessary to match.
 - *This is even more true of bss, where we have trouble with IDO unpredictably reordering it in certain files.*
 - For small arrays or simple data that is used in only one function, we usually inline it, if it fits in the ordering.
 - Generally data that is only used by the draw functions is put down near them: this is one of the few consistencies in ordering of actors' functions.
@@ -192,14 +204,14 @@ All functions should go in the main C file in the same order as the assembly (th
   #define ENDG_GET_3E0(thisx) (((thisx)->params & 0x3E0) >> 5)
   ```
 
-  and a documented example, `z_en_firefly.h`
+  and a documented example from Majora's Mask, `z_en_firefly.h`
 
   ```c
   #define KEESE_INVISIBLE (1 << 0xF)
   #define KEESE_GET_MAIN_TYPE(thisx) ((thisx)->params & 0x7FFF)
   ```
 
-- In a similar manner, actors that use `home.rot.(x|y|z)` like params should also macros made for accesses and writes. (See, e.g. `z_obj_bean.h`.)
+- In a similar manner, actors that use `home.rot.(x|y|z)` like params should also macros made for accesses and writes. (See, e.g. `z_obj_bean.h` from Majora's Mask.)
 - Stuff that only the actor itself will use goes in the C file unless needed in the header.
 - Anything actor-specific that might be used by another file goes in the header, in particular params access macros.
 - Anything that is expected to have widespread use should go in the appropriate header file. eg z64_math.h, gfx.h, macros.h