Contributing

This chapter concerns the writers of this tutorial. When writing, there are a few standards to follow in order to maximize consistency throughout the tutorial.

Address explanations

This section concerns the way addresses are written, as to avoid confusion.

Direct page

• For the sake of simplicity and explanation, all direct page addresses ("$xx") shall use address $7E0000 as its base. This shall be emphasized in code block comments, as well as explanations.

Example:

LDA #$42
STA $08            ; Store the value $42 into address $7E0008

Absolute addressing

• All absolute addresses ("$xxxx") use address $7E0000 as its base, if the address is between $0000-$7FFF inclusive. For addresses between $8000-$FFFF, address $000000 shall be used as its base instead. This shall be emphasized in code block comments, as well as explanations.

Example:

LDA $8002            ; Load the value at address $008002 into A
STA $1008            ; Store that value into address $7E1008

Styling

This section concern the styling of the document.

Inline code

• All opcodes and instructions shall be surrounded by the markdown backtick (`), regardless of the context.

Example: The opcode LDA is used to load values into the A register. Thus, LDA #$49 loads the value $49 into A. This then can be increased to the value $4A by using INC A.

Markdown tables

• Sentences and phrases within table cells generally shouldn't end with a period.

• Tables introducing opcodes should have the opcodes in bold and have at least the three columns in below example:

Opcode	Full name	Explanation
LDA	Load into accumulator	Load a value into A

Terminology

This section concerns the usage of certain words in certain context.

Rule	Example
When referring to the Ricoh 5A22 processor, use the SNES instead	The SNES is capable of entering 8-bit or 16-bit mode
When referring to a specific area in the SNES memory, always prepend address to it, preferably with the memory area (i.e. RAM)	(The) RAM address $7E0000 contains [...]
When referring to the accumulator (A) or the index registers (X and Y), just use A, X or Y	A is now in 8-bit mode. X is used to index addresses
When referring to values, always prepend value to it	A contains the value $00

Example codes

• Code shall use indentation when there are labels, sublabels or plus/minus labels on the same line as an instruction. The amount of indentation equals the length of the longest aforementioned type of label in the code block, including colon (":"), plus two additional spaces.

  • Code shall use whitespace for indentation, not tabs.

• Opcodes are written entirely in uppercase (e.g.: LDA).

• Labels are written in PascalCase (e.g.: Label1:).

• Sublabels are written entirely in lower, underscore-case and the name should semantically suit the parent label, without redundancy (e.g.: .return).

• Defines are written in PascalCase (e.g.: !SomeDefine).

• Direct data (db, dw, dl, dd), indexers (,x, ,y, ,s) and opcode length specifiers (.b, .w, .l) are written entirely in lowercase.

• Comment indicators (i.e. ;) shall start on column 20, and left-padded by whitespace, not tabs.

  • If there's no space for a comment on column 20, it should start on the same line anyway.

• In fact, never use tabs.

• Comment indicators shall be followed by a whitespace, before the comment itself.

• There will be an extra new line after the opcodes RTS, RTL, RTI, JMP, JML, BRA, BRL.

• These are guidelines which are to be followed as strictly as possible, but there may be exceptional cases. Use your best judgment.

Examples:

SomeLabel:         ; This label is on its own line
LDA.b #$42
STA $00            ; This is a comment
RTS

.table:
db $01,$02,$03,$04 ; Another comment

.second_table:
db $01,$02,$03,$04,$01,$02,$03,$04 ; An exceptional comment

TestLabel:  LDA #$02 ; This label is on the same line as an instruction
            STA $01
            BNE +
            NOP
+           RTS      ; The code is indented according to "TestLabel", not "+"