Update README.md

applesoft/nfs/README.md

@@ -69,11 +69,12 @@ The actual difference of **723 cycles** does not really matter. What is importan
 
 1. [Use variables as placeholders for constant values](#1-use-variables-as-placeholders-for-constant-values): accessing a known value in a variable is faster than deciphering values in code.
 2. [Declare your most used variables first](#2-declare-your-most-used-variables-first): create and/or reference the variables you're going to use the most as soon as possible
+3. [Use one-letter variables names whenever possible](#3-use-one-letter-variables-names-whenever-possible): longer variables names take longer to parse.
 
 ## Calculations
 
-3. [Use addition instead of multiplication by 2](#3-use-addition-instead-of-multiplication-by-2): addition of the same variable twice is faster than multiplying the variable by 2
-4. [Addition is faster than subtraction](#4-addition-is-faster-than-subtraction): avoid subtraction whenever possible but don't use negative constants.
+4. [Use addition instead of multiplication by 2](#4-use-addition-instead-of-multiplication-by-2): addition of the same variable twice is faster than multiplying the variable by 2
+5. [Addition is faster than subtraction](#5-addition-is-faster-than-subtraction): avoid subtraction whenever possible but don't use negative constants.
 
 (and many others) coming soon... 
 
@@ -329,9 +330,60 @@ Line 20 here takes 5500 cycles, that's 136 cycles more. Nothing too drastic but
 
 The same kind of process should be made with the variable ``U``. Should it be declared before ``M`` ? With these two snippets, ``U`` is referenced only once, whereas ``M`` could be referenced twice when ``X>M`` ... but it's probable that ``U`` (placeholder for the constant ``1``) is used elsewhere in the main game loop, while ``M`` has not many other uses than to check X-coordinates maximum limit ... so ``U`` will probably be more efficiently referenced if declared before ``M``.
 
+## 3) Use one-letter variables names whenever possible
+
+### 🍎Forget about meaningful variable names
+
+Applesoft only supports variables names made of one or two characters. The first character **must** be a letter, while the second character may be a letter **or** a number.
+
+It is allowed to name variables with more characters but these are ignored, meaning that variable ``ABRACADABRA`` is really stored as ``AB`` and maybe referenced later in the code with that name. It also means that you can't really have a variable named ``A10`` as it will be in fact variable ``A1``.
+
+This behavior is true for any kind of variable (float, integer, string, array of (float/integer/strings), and even ``DEF FN`` which are just referenced as another kind of variable). It means that for every variable type, you can't have more than 26 + 26 * (26+10) variables = 962 different variables names.
+
+The problem is that the Applesoft parser will take 56 cycles for every extra character in a variable name.
+
+```basic
+10 A=17
+20 END
+```
+
+Line 10 takes 2776 cycles. Now, let's use variable ``AB`` instead of ``A``:
+
+```basic
+10 AB=17
+20 END
+```
+
+Line 10 now takes 2832 cycles, that's 56 more cycles. Now, for the extreme example:
+
+```basic
+10 ABRACADABRA = 17
+20 END
+```
+
+Line 10 takes now 3336 cycles, which is 504 cycles slower, which is exactly 56 cycles for each of the extra 9 characters after ``AB``.
+
+Every time a variable is parsed, it takes 56 more cycles to parse a 2-characters variable name than if the variable name was only 1 character. And this is true for every use of the variable: assignment, calculation, print, memory read/write, 6502 subroutine call, etc.
+
+### 🍎Recommendations
+
+- Use one-letter variable names as much as possible in your main loop. 
+  
+  - It means, **yes**, you need to avoid ``OX,OY`` for the previous cycle's ``X,Y`` coordinates. 
+  
+  - If needed, re-use variables names declared before starting the main loop if these variables hold values you don't care about anymore.
+  
+  - Remember to [declare your most used variables first](#2-declare-your-most-used-variables-first) !
+
+- Use as few two-characters variables names as possible in your main loop, as each 2-characters variable name will take 56 more cycles **just** to parse the name of the variable in the code.
+
+- **NEVER** use more than two-characters variables names in your main loop <sup>(*)</sup>.
+
+<sup>(*) you should apply this rule even if you're not looking for speed as confusion is waiting behind the corner: variable ``LEVEL`` and variable ``LENGTH`` both refer to variable ``LE`` ...</sup>
+
 # Calculations
 
-## 3) Use addition instead of multiplication by 2
+## 4) Use addition instead of multiplication by 2
 
 ### 🍎 Multiplication is just another form of addition.
 
@@ -435,7 +487,7 @@ This second snippet illustrates the speed if the result of ``A/B`` is of any int
 
 line 20 takes only 2409 cycles. Using ``20 E=C*D`` would take 2283 cycles more.
 
-## 4) Addition is faster than subtraction
+## 5) Addition is faster than subtraction
 
 ### 🍎 Simple cycles comparison