From 64517738cef8fbc2644723eb39f141958ae57639 Mon Sep 17 00:00:00 2001
From: Miquel Sabaté Solà <mikisabate@gmail.com>
Date: Mon, 24 Feb 2025 14:56:58 +0100
Subject: Clarify on labels and indentation levels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Miquel Sabaté Solà <mikisabate@gmail.com>
---
 README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 54 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 33a4dd9..13f0089 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@ good:
     lda #1
 ```
 
-A new indentation level is to be given after the start of a function:
+Introduce a new indentation level after any label:
 
 ``` assembly
 function1:
@@ -72,7 +72,9 @@ function2:
     lda #1   ; good!
 ```
 
-Labels, though, are to be kept at the previous indentation level:
+That being said, if the label exists in relation to another one, then it ought
+to be kept at the previous indentation level. For example, labels for control
+flow inside of a function:
 
 ``` assembly
 function1:
@@ -86,25 +88,50 @@ function2:
     jmp @label
 ```
 
+The same would apply to a function which has some pre-computed data for some of
+its logic:
+
+``` assembly
+function1:
+    ldx #$00
+    lda data, x
+    ;; Do something
+    rts
+data:
+    .byte $01, $02
+```
+
 The rationale for this is that labels ought to be clearly visible, and by being
-at a different indentation level as instructions they certainly stick out. The
-recommended `@` prefix for labels (see [Naming
-conventions](#naming-conventions)) disambiguates with the name of the function
-clearly as well. For a similar reason labels are to be put on their own line:
+at a different indentation level as instructions they certainly stick out.
+Moreover, note that every instruction for a function is kept at the same
+indentation level regardless of its flow. The recommended `@` prefix for labels
+(see [Naming conventions](#naming-conventions)) further disambiguates with the
+name of the function as well.
+
+One could argue that labels for control flow could be put at the same
+indentation level, and hence you would be able to clearly denote where loops or
+branches are inside of a given function. Hence, having something such as:
 
 ``` assembly
-bad: lda #1
-good:
+function1:
     lda #1
-
-;; Yes, even data.
-bad: .byte $02
-good:
-    .byte $02
+    @loop:
+        ldx #00
+        jmp @loop
+    rts
 ```
 
-Introduce a new indentation level inside of `.proc`, `.macro`, `.repeat`, `.if`
-and similar control statements which expect a block of code inside. Thus:
+I have the following disagreements with this approach:
+
+1. It artificially makes it look like a higher-level programming language (e.g.
+   there is no lexical scoping).
+2. I feel like labels (e.g. `@loop` in the example above) are easier to miss.
+3. Having multiple indentation levels is already a code smell: avoid too much
+   complexity on your functions as you ought to be as performant as possible.
+
+In a similar spirit, introduce a new indentation level inside of `.proc`,
+`.macro`, `.repeat`, `.if` and similar control statements which expect a block
+of code inside. Thus:
 
 ``` assembly
 .proc bad
@@ -116,14 +143,19 @@ lda #1
 .endproc
 ```
 
-One could argue that after a label we could introduce another indentation level.
-That is certainly tolerable, but I have the following disagreements with this
-approach:
+Last but not least, and again for clarity's sake, labels are to be put on their
+own line:
 
-1. It artificially makes it look like a higher programming language (e.g. there
-   is no lexical scoping).
-2. Having multiple indentation levels is already a code smell: avoid too much
-   complexity on your functions as you ought to be as performant as possible.
+``` assembly
+bad: lda #1
+good:
+    lda #1
+
+;; Yes, data too.
+bad: .byte $02
+good:
+    .byte $02
+```
 
 ## Line endings and the likes
 
-- 
cgit v1.2.3