1 files changed, 236 insertions, 0 deletions
diff --git a/js/scripting-lang/tutorials/16_Best_Practices.md b/js/scripting-lang/tutorials/16_Best_Practices.md
new file mode 100644
index 0000000..8a6b246
--- /dev/null
+++ b/js/scripting-lang/tutorials/16_Best_Practices.md
@@ -0,0 +1,236 @@
+# Operator Spacing Best Practices
+
+## Why Spacing Matters
+
+The language uses spacing to distinguish between different types of operators and make expressions unambiguous. Proper spacing follows functional language conventions and makes your code more readable.
+
+## Minus Operator Spacing
+
+### Unary Minus (Negative Numbers)
+
+Unary minus works without parentheses and requires no leading space:
+
+```plaintext
+/* ✅ CORRECT - Unary minus without parentheses */
+-5;              /* negate(5) */
+-3.14;           /* negate(3.14) */
+-x;               /* negate(x) */
+f -5;            /* f(negate(5)) */
+map double -3;   /* map(double, negate(3)) */
+```
+
+### Binary Minus (Subtraction)
+
+Binary minus requires spaces on both sides:
+
+```plaintext
+/* ✅ CORRECT - Binary minus with spaces */
+5 - 3;           /* subtract(5, 3) */
+10 - 5;          /* subtract(10, 5) */
+x - y;           /* subtract(x, y) */
+3.14 - 1.5;      /* subtract(3.14, 1.5) */
+```
+
+### Legacy Syntax (Still Works)
+
+Legacy syntax continues to work for backward compatibility:
+
+```plaintext
+/* ✅ CORRECT - Legacy syntax still works */
+(-5);            /* negate(5) - explicit grouping */
+f (-5);          /* f(negate(5)) - explicit grouping */
+5-3;             /* subtract(5, 3) - legacy fallback */
+```
+
+### Complex Expressions
+
+Complex expressions with mixed operators work correctly:
+
+```plaintext
+/* ✅ CORRECT - Complex expressions */
+-5 + 3;          /* add(negate(5), 3) */
+-5 - 3;          /* subtract(negate(5), 3) */
+-5 * 3;          /* multiply(negate(5), 3) */
+-5 + 3 - 2;      /* subtract(add(negate(5), 3), 2) */
+```
+
+## General Operator Spacing
+
+### Binary Operators
+
+All binary operators should have spaces around them:
+
+```plaintext
+/* ✅ CORRECT - Binary operators with spaces */
+5 + 3;           /* add(5, 3) */
+5 * 3;           /* multiply(5, 3) */
+5 / 3;           /* divide(5, 3) */
+5 % 3;           /* modulo(5, 3) */
+5 ^ 3;           /* power(5, 3) */
+```
+
+### Comparison Operators
+
+Comparison operators require spaces:
+
+```plaintext
+/* ✅ CORRECT - Comparison operators with spaces */
+5 = 3;           /* equals(5, 3) */
+5 != 3;          /* notEquals(5, 3) */
+5 < 3;           /* lessThan(5, 3) */
+5 > 3;           /* greaterThan(5, 3) */
+5 <= 3;          /* lessEqual(5, 3) */
+5 >= 3;          /* greaterEqual(5, 3) */
+```
+
+### Logical Operators
+
+Logical operators require spaces:
+
+```plaintext
+/* ✅ CORRECT - Logical operators with spaces */
+true and false;  /* logicalAnd(true, false) */
+true or false;   /* logicalOr(true, false) */
+true xor false;  /* logicalXor(true, false) */
+```
+
+### Unary Operators
+
+Unary operators (except minus) don't require special spacing:
+
+```plaintext
+/* ✅ CORRECT - Unary operators */
+not true;        /* logicalNot(true) */
+not false;       /* logicalNot(false) */
+```
+
+## When to Use Parentheses
+
+### Explicit Grouping
+
+Use parentheses when you need explicit control over precedence:
+
+```plaintext
+/* ✅ CORRECT - Explicit grouping */
+(-5) + 3;        /* add(negate(5), 3) - explicit grouping */
+f (-5);          /* f(negate(5)) - explicit grouping */
+(5 + 3) * 2;     /* multiply(add(5, 3), 2) - explicit grouping */
+```
+
+### Complex Expressions
+
+Use parentheses to make complex expressions more readable:
+
+```plaintext
+/* ✅ CORRECT - Complex expressions with parentheses */
+(-5 + 3) * 2;    /* multiply(add(negate(5), 3), 2) */
+(-5) * (3 + 2);  /* multiply(negate(5), add(3, 2)) */
+```
+
+## Common Patterns
+
+### Function Calls with Negative Numbers
+
+```plaintext
+/* ✅ CORRECT - Function calls with negative numbers */
+double -5;       /* double(negate(5)) */
+map double -3;   /* map(double, negate(3)) */
+filter is_negative {-5, 0, 5};  /* filter(is_negative, {-5, 0, 5}) */
+```
+
+### Comparisons with Negative Numbers
+
+```plaintext
+/* ✅ CORRECT - Comparisons with negative numbers */
+-5 >= 0;         /* greaterEqual(negate(5), 0) */
+-5 < 0;          /* lessThan(negate(5), 0) */
+is_negative -5;  /* is_negative(negate(5)) */
+```
+
+### Arithmetic with Mixed Operators
+
+```plaintext
+/* ✅ CORRECT - Mixed arithmetic */
+-5 + 3 - 2;      /* subtract(add(negate(5), 3), 2) */
+5 * -3 + 2;      /* add(multiply(5, negate(3)), 2) */
+(-5) * 3 + 2;    /* add(multiply(negate(5), 3), 2) */
+```
+
+## Best Practices Summary
+
+### Do's
+
+- ✅ **Use spaces around binary operators**: `5 - 3`, `5 + 3`, `5 * 3`
+- ✅ **Unary minus works without parentheses**: `-5`, `f -5`
+- ✅ **Use parentheses for explicit grouping**: `(-5)`, `(5 + 3) * 2`
+- ✅ **Use spaces around comparison operators**: `5 = 3`, `5 < 3`
+- ✅ **Use spaces around logical operators**: `true and false`
+
+### Don'ts
+
+- ❌ **Don't omit spaces around binary operators**: `5-3`, `5+3` (legacy fallback)
+- ❌ **Don't add spaces after unary minus**: `- 5` (legacy fallback)
+- ❌ **Don't use inconsistent spacing**: `5- 3`, `5 -3` (legacy fallback)
+
+### When in Doubt
+
+- **Use spaces around binary operators** - it's always correct and more readable
+- **Unary minus works without parentheses** - `-5` is the preferred syntax
+- **Use parentheses for explicit grouping** - when you need to control precedence
+- **Follow functional language conventions** - spaces around operators are standard
+
+## Examples in Context
+
+### Data Processing
+
+```plaintext
+/* Process data with proper spacing */
+data : {-5, 0, 5, 10, 15};
+is_positive : x -> x > 0;
+double : x -> x * 2;
+sum : x -> reduce add 0 x;
+
+/* Pipeline with proper spacing */
+result : sum map double filter is_positive data;
+/* Reads: sum (map double (filter is_positive data)) */
+/* Result: 60 (positive: {5,10,15}, doubled: {10,20,30}, sum: 60) */
+```
+
+### Validation Logic
+
+```plaintext
+/* Validation with proper spacing */
+validate_age : age -> (age >= 0) and (age <= 120);
+validate_salary : salary -> (salary >= 0) and (salary <= 1000000);
+
+/* Test validation */
+test1 : validate_age -5;    /* false */
+test2 : validate_age 25;    /* true */
+test3 : validate_salary 50000;  /* true */
+```
+
+### Mathematical Expressions
+
+```plaintext
+/* Mathematical expressions with proper spacing */
+calculate_discount : price discount_rate -> 
+  price - (price * discount_rate);
+
+apply_tax : price tax_rate -> 
+  price + (price * tax_rate);
+
+/* Use the functions */
+final_price : apply_tax (calculate_discount 100 0.1) 0.08;
+/* Result: 97.2 (discount: 90, tax: 7.2) */
+```
+
+## Key Takeaways
+
+1. **Spacing distinguishes operators** - unary vs binary minus
+2. **Unary minus works without parentheses** - `-5` is preferred
+3. **Binary operators need spaces** - `5 - 3`, `5 + 3`, `5 * 3`
+4. **Legacy syntax still works** - but spaces are recommended
+5. **Parentheses for explicit grouping** - when you need control
+6. **Follow functional conventions** - spaces around operators are standard
+
+**Remember**: Proper spacing makes your code more readable and follows functional language conventions! 🚀
\ No newline at end of file