docs: add a style guide for code

Inspired by pokecrystal style guide.

STYLE.md

@@ -0,0 +1,121 @@
+# Style Guide
+
+Some of the code will disagree with this guide. Older code is less likely to be correct. Use your best judgement.
+
+When you come across an edge case that isn't referenced in this guide, please add it.
+
+## Comments
+
+```asm
+; Use spaces for indentation and alignment.
+
+; Comments lead with spaces after the semicolon.
+
+; 80 char soft limit. This isn't enforced, but you should try to keep lines from being any longer.
+; rgbasm doesn't have newline escapes so there's no avoiding exceeding the limit for longer macros.
+
+; Code comments should be wrapped to whatever
+; is most readable rather than what's closest
+; to the 80 char limit.
+
+; Comments should go above the code they're describing, not below, and be aligned with the code.
+
+; Functions are commented with unindented comments
+SomeFunction::
+    ; Code is commented with an indentation
+    ld  a, [hl]
+    add b
+    ld  [hl], a
+    ret
+```
+
+## Labels
+
+```asm
+; ROM Labels
+PascalCase:   ; label
+PascalCase::  ; global label
+.snakeCase    ; local jump
+.PascalCase:  ; an atomic chunk of code or data that's local
+; don't define unused labels when a comment would do
+
+; Labels are prefixed with lower case letters depending on location
+wPascalCase: ; wram
+sPascalCase: ; sram
+vPascalCase: ; vram
+hPascalCase: ; hram
+PascalCase:  ; rom
+
+; Some constants are also prefixed
+DEF rBGP EQU $FF47 ; hardware register
+
+; Most other constants should be upper case
+DEF UPPER_CASE EQU 1
+
+; Long lists of constants should be aligned
+DEF SHORT_CONSTANT       EQU 1
+DEF LONGER_CONSTANT      EQU 2
+DEF PRETTY_LONG_CONSTANT EQU 3
+DEF TINY                 EQU 4
+
+DEF BUT_ONLY_RELATED_CONSTANTS EQU 5
+```
+
+## Code
+
+```asm
+SomeFunction::
+    ; Instructions are indented with 4 spaces
+    ldh  a, [hIsGBC]
+    and  a
+    jr   z, .ramSwitchEnd
+
+    ; Instructions operands are vertically aligned,
+    ; so that the first operand is always on the same column
+    jr   z, .end
+    push bc
+    ; (Which means this alignement is incorrect)
+    jr z, .end
+    push bc
+
+; Hexadecimal constants are uppercase
+func_02A_56AF::
+    ld   a, $0C
+```
+
+## Directives
+
+```asm
+; meta and high-level directives should be uppercase
+SECTION "section", ROMX
+INCLUDE "filename"
+INCBIN "filename"
+MACRO my_macro
+  nop
+ENDM
+DEF TEST EQUS "test"
+PURGE TEST
+DEF TEST EQU 2
+
+; the rest is up to you, just be consistent (prefer lowercase)
+set X, 1
+rept 10
+  nop
+endr
+```
+
+## Macros
+
+```asm
+MACRO when_in_doubt_lowercase
+
+; data macros should be lowercase
+    db 1
+    dw 2
+    my_macro SOME_CONSTANT
+
+; code macros are currently lowercase but this seems to be causing confusion with actual instructions
+    ld b, TEST
+    farcall DistantFunction
+    ret
+```