Some Style Guide for GBASM

This style guide is based on the pret style guide as seen here.

Working on some disasm stuff, hopefully this should be a reminder.

Code

; For code, use ONE TAB, followed by the INSTRUCTION, followed by ARGUMENTS
; separated with ONE SPACE each.

.SomeData:
    db 0 ; flags

.SomeCode:
    ld a, 2
    call .SomewhereElse
    jr .SomeCode

; Use spacing for math expressions.

    ld hl, wSomething + 10
    ld de, wFoobar + FOO_OFFSET

; Capitalize EQU.

NUM_SOMETHING EQU const_value - 1
UP_ARROW      EQU $f0

; Make sure the spacing lines up neatly. Spaces, not tabs, are recommended
; precisely because of this.

\1Field0c::      db
\1Field0d::      db
\1Field0e::      db
\1StopDelay::    db

; Don't have trailing spaces.
; Add newlines at the end of files. This makes it slightly easier to
; contribute new code.

; Add blank lines between different points of data. For a list of pointers,
; the table and the datapoint is separated by a blank line.
; Between each datapoint, separate each with blank lines.

Table::
    dw .Dataone
    dw .Datatwo
    dw .Dataone
    dw .Datathree

.Dataone:
    db 0, 1, 2, 3

.Datatwo:
    db 4, 5, 6, 7

.Datathree:
    db 8, 9, 10, 11

; Use HLI. Do not use HL+ / HL-, nor LDI / LDD. (pret)

    xor a
    ld c, 6
    ld hl, wRoom
.loop
    ld [hli], a
    dec c
    jr nz, .loop

; When the meaning of a hard-coded number isn't obvious, it should
; just stay as hex. (pret)

; Make sure there are no address comments - you should check the SYM files
; for that.

Comments

; Use tabs for indentation, and spaces for alignment.
; When tabs get in the way of alignment, use spaces instead.

; 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.

; capitalization and punctuation dont matter
; but it should be consistent with the surroundings

; Space out paragraphs with two newlines. Don't put ;s on blank lines.

; Code comments should be wrapped to whatever
; is most readable rather than what's closest
; to the 80 char limit.

; Especially since most code is going to be
; under 30 chars per line, including tabs.

; Comments should go above the code they're describing, not below, and not inline.

    ld a, [hl]
    add b
    ld [hl], a
    ret

; Avoid comments on the same line as instructions.

    cp 10
    jr c, .elsewhere ; don't do this

; If you have a larger comment and want to make
; a side note on a snippet of code:

    ; You can indent the comment,
    ; but each line should be shorter
    ; and spaced away from the parent comment

    halt
    nop

; To comment out code, put the ; before the tab indent.

;   nop
    cp 10
;   jr c, .bye
    ret

; Generally, avoid the following:

Function0deadb33f: ; do foo
    ld a, 1
    ret

SomeFunc:
    ld a, 2
    ld b, 6
    call Function0deadb33f ; do foo
    ret

; /end avoid

Labels

; ROM Labels

; Use one colon for code-wide labels.

PascalCase: ; label

; Double colons are exported by RGBASM, so use that for global labels.

PascalCase::

; No colons for local jump

.snake_case

; Use one colon for an atomic chunk of code or data that's local

.PascalCase:

; 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
rBGP EQU $ff47 ; hardware register

; Most other constants should be upper case
UPPER_CASE EQU 1


; Long lists of constants should be aligned
SHORT_CONSTANT       EQU 1
LONGER_CONSTANT      EQU 2
PRETTY_LONG_CONSTANT EQU 3
TINY                 EQU 4

BUT_ONLY_RELATED_CONSTANTS EQU 5

Directives

; meta and high-level directives should be uppercase
SECTION "section", ROMX
INCLUDE "filename"
INCBIN "filename"
my_macro: MACRO
    nop
ENDM
TEST EQUS "test"
PURGE TEST
TEST EQU 2

; data macros should be lowercase
    db 1
    dw 2
    my_macro SOME_CONSTANT

    ; one exception is RGB
    RGB 31, 31, 31

; code macros are currently lowercase but this seems to be causing confusion with actual instructions
    ld b, TEST
    farcall DistantFunction
    ret

; the rest is up to you, just be consistent (prefer lowercase)
set X, 1
rept 10
    nop
endr

Macros

when_in_doubt_lowercase: MACRO

; only shift if it's required or more readable

    ; dont
    db \1
    shift
    db \1

    ; do
rept 10
    db \1
    shift
endr

    ; do
    db \1, \2, \3, \4, \5
    shift 5
    db \1, \2, \3, \4, \5

ENDM


UPPER_CASE_IS_OK_SOMETIMES: MACRO

; but I can't think of any examples besides ACRONYMS

ENDM