Merge branch 'master' into intoinside/issue1

Author: intoinside

CONTRIBUTING.md

@@ -1,7 +1,64 @@
 # Welcome to contributing guide
 TBD
+
 ## Guide to contributing code
-TBD
+
+### Declaration case type
+Labels must use the **Snake Case with all capital letters**.
+<pre>
+.label PAGE0_PAGE_POINTER   = $D507
+</pre>
+
+Macro must use the **Pascal Case**.
+<pre>
+.macro BasicUpstart128() { }
+</pre>
+
+Functions must use the **Camel Case**.
+<pre>
+.function incArgument() { }
+</pre>
+
+### Argument check
+If a macro or function has arguments that can only take on certain values, it is advisable to insert checks to ensure correct use.
+You can use the .errorif keyword to raise an error.
+
+``` Assembly
+.macro FillMemory(address, length, value) {
+  .errorif (length < 5 || length > 255), "length must be from 5 to 255"
+...
+}
+```
+
+It is also a good idea to add assertions at the end of the macro body to check that the error is raised correctly.
+
+``` Assembly
+.asserterror "FillMemory($A000, 4, 10)", { FillMemory($A000, 4, 10) }
+.asserterror "FillMemory($A000, 256, 10)", { FillMemory($A000, 256, 10) }
+```
+
+### Static test
+Static testing should be performed to verify that the correct code is produced. At the end of each macro, add one or more assertions to compare the code generated by the macro with the expected code.
+
+``` Assembly
+.macro SetCommonRAM(config) {
+    lda #config
+    sta Mmu.RAM_CONFIG
+}
+.assert "SetCommonRAM(COMMON_RAM_16K | COMMON_RAM_BOTH) sets accumulator to 0f", { SetCommonRAM(Mmu.COMMON_RAM_16K | Mmu.COMMON_RAM_BOTH) }, {
+  lda #%00001111; sta $d506
+}
+```
+
+Static testing is very important especially where the code can vary depending on the arguments with which a macro is called.
+
+### Hex values
+
+Hex values should be written with two or four characters as needed. The letters should be capitalized.
+
+``` Assembly
+.label CONFIGURATION        = $D500
+```
 
 ## Guide to contributing documentation
 ### File header
@@ -77,19 +134,3 @@ or output value
 #### Other keywords under evaluation
 * a @example keyword (optional) for pointing to other source code where method is used
 * a @note keyword (optional) for a simple usage code
-
-### Declaration case type
-Labels must use the **Snake Case with all capital letters**.
-<pre>
-.label PAGE0_PAGE_POINTER   = $D507
-</pre>
-
-Macro must use the **Pascal Case**.
-<pre>
-.macro BasicUpstart128() { }
-</pre>
-
-Functions must use the **Camel Case**.
-<pre>
-.function incArgument() { }
-</pre>