diff options
Diffstat (limited to 'js/scripting-lang/tutorials/16_Best_Practices.md')
| -rw-r--r-- | js/scripting-lang/tutorials/16_Best_Practices.md | 236 |
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 |