Add an explanation of how to format Yarns.

1 files changed, 92 insertions, 0 deletions

diff --git a/TESTING b/TESTING
index fc5f400..8c754c7 100644
--- a/TESTING
+++ b/TESTING
@@ -117,6 +117,98 @@ The fundamental parts of the `testing/` directory are
 * `03_*.yarn` These tests are more integration tests which look to simulate
   more complex user use-cases.
 
+Formatting Yarn tests
+=====================
+
+Yarns are indented code blocks surrounded by documentation.
+For the sake of readability, this codebase also has the following rules:
+
+1.  Make use of `AND` rather than repeating.
+
+    This cuts down on the noise.
+
+2.  Don't use `AND` at the beginning of a code block.
+
+    This makes it difficult to recall which type the statement is.
+
+    When reading the scenario in-flow you end up needing to backtrack
+    to the previous code-block to see where you continue from.
+
+3.  Indent everything to 4 spaces.
+
+    Markdown supports tabs as indentation too,
+    but some editors normalise tabs to spaces
+    and others may normalise spaces to tabs.
+
+    When they disagree with how wide a tab should be
+    they make the indentation super weird.
+
+    In a perfect world everyone's editor would be correctly configured,
+    but in our imperfect world, we use spaces for indentation.
+
+4.  In each code block, right-justify the first word.
+
+    This makes the text line up in a way that is aesthetically pleasing
+    and easier to scan visually.
+
+    So if you have a `GIVEN`, `WHEN`, `THEN` and `AND`, align as:
+
+        GIVEN foo exists
+         WHEN foo is barred
+         THEN foo is bazzed
+          AND foo is quxed
+
+5.  Justification doesn't span multiple blocks.
+
+    If a block contains no GIVEN then do not indent to 5 spaces
+    to align with other code blocks.
+
+    This adds unnecessary padding,
+    and if the explanatory text between the blocks grows
+    then there becomes no need to align with an earlier block.
+
+    So if you have two blocks:
+
+        GIVEN foo exists
+        WHEN foo is barred
+        THEN foo is bazzed
+
+        WHEN foo is poked
+        THEN foo is notified
+
+    Do not justify as:
+
+        GIVEN foo exists
+         WHEN foo is barred
+         THEN foo is bazzed
+
+         WHEN foo is poked
+         THEN foo is notified
+
+    Justify as:
+
+        GIVEN foo exists
+         WHEN foo is barred
+         THEN foo is bazzed
+
+        WHEN foo is poked
+        THEN foo is notified
+
+5.  Put `SCENARIO`, `ASSUMING` and `FINALLY` in a separate code-block.
+
+    Yarn will appropriately merge these into the normal flow,
+    and if they were kept in the same code-block
+    they would introduce unnecessary padding for everything else.
+
+    `SCENARIO`, `ASSUMING` and `FINALLY` may go in the same code blocks.
+
+6.  Put `FINALLY` at the end of the scenario.
+
+    Yarn will always run `FINALLY` at the end,
+    and while it may be appealing to put the `FINALLY` with the `GIVEN`
+    that requires cleaning up,
+    this often reads strangely and causes unnecessary padding.
+
 Tip and tricks when writing tests for Gitano
 ============================================