This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Document status: DRAFT

1. Conventions documentation

A short paragraph introducing and clarifying the conventions used in the document must be placed (and kept updated) in the top of the document.

2. Monospaced text, code snippets, code boxes

• No ligatures

3. Pseudocode

• Assignment: :=
• Comparison: =, ≠, <, >, ≤, ≥
• Arithmetic: +, −, ×, /, mod
• Floor/ceiling: ⌊, ⌋, ⌈, ⌉. a := ⌊b⌋ + ⌈c⌉
• Logical: and, or, not
• Sums, products: Σ Π

References:

1. http://www.cs.cornell.edu/courses/cs482/2003su/handouts/pseudocode.pdf
2. https://blog.usejournal.com/how-to-write-pseudocode-a-beginners-guide-29956242698
3. https://cs.wmich.edu/gupta/teaching/cs3310/sp18cs3310web/lecture%20notes%20cs3310/PseudocodeBasics.pdf
4. https://en.wikipedia.org/wiki/Pseudocode#Mathematical_style_pseudocode

4. Units and prefixes:

Use Binary Prefixes (Ki, Mi) for Bytes. E.g.:

1 MiB = 2^20 bytes = 1,048,576 bytes
1 KiB = 2^10 bytes = 1,024 bytes

• Abbreviate bytes as B when used with a prefix. Spell out bits as bits, even when used with a prefix to avoid ambiguity. When used as a unit suffix, unit names are always singular, so it should be "20 kbit", not "20 kbits". (Also, "bytes" as a word is fine, just like "30 meters" is a valid way of talking about that length. But "Mbyte" and the like should go away.)
• Hexadecimal values are uppercase and prefixed with $. E.g. $ABCD. To prevent clutter, don't use a prefix for hex numbers when it's clear from the context that a number is hexadecimal. For example addresses and lists of opcodes. In those cases, zero pad, even for smaller number. (Eg: 0000-3FFF instead of 0-3FFF.
• Put a space between numbers and their unit (ISO).
• Decimal numbers must be written with a decimal point instead of a comma.
• Binary numbers must be accompanied by the "binary" word.
• Other units (such as Hertz) may use the decimal prefixes (K = 1000, M = 1000000)

References:

• https://superuser.com/questions/938234/size-of-files-in-windows-os-its-kb-or-kb#comment1275467_938259

Discussion:

• #76, #55

5. 8 bits / 8-bit

• "8 bits" and "8-bit" have different usages in the English language. The former is used when talking about the quantity ("a byte has 8 bits"), while the latter is used as an adjective ("8-bit bytes are nowadays standard"). "8bit" is obviously wrong, and "8 bit" is likewise incorrect.

Discussion:

• #102

6. Horizontal Blanking Interval, Vertical Blanking Interval

• VBlank, HBlank

Discussion:

• #94

7. Mentioning models

We use the console codenames, so:

• DMG
• SGB
• MGB
• SGB2
• CGB
• AGB

8. Spacing and hyphenation of some terms

• "tile map", not "tilemap"
• "wavelength", not "wave length" (#350 (comment))

9. Numerical ranges

Those should either be written out (1 to 42), or use an "n-dash" – (can also be written as the HTML entity –).

Discussion:

• #341 (comment)

10. Spellings

Use American English spellings and variants.