diff options
Diffstat (limited to 'js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-16_Best_Practices.html')
| -rw-r--r-- | js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-16_Best_Practices.html | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-16_Best_Practices.html b/js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-16_Best_Practices.html new file mode 100644 index 0000000..819884e --- /dev/null +++ b/js/scripting-lang/docs/baba-yaga/0.0.1/tutorial-16_Best_Practices.html @@ -0,0 +1,226 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width,initial-scale=1"> + <title>16_Best_Practices - Documentation</title> + + <script src="scripts/prettify/prettify.js"></script> + <script src="scripts/prettify/lang-css.js"></script> + <!--[if lt IE 9]> + <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script> + <![endif]--> + <link type="text/css" rel="stylesheet" href="https://code.ionicframework.com/ionicons/2.0.1/css/ionicons.min.css"> + <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css"> + <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css"> +</head> +<body> + +<input type="checkbox" id="nav-trigger" class="nav-trigger" /> +<label for="nav-trigger" class="navicon-button x"> + <div class="navicon"></div> +</label> + +<label for="nav-trigger" class="overlay"></label> + +<nav> + <li class="nav-link nav-home-link"><a href="index.html">Home</a></li><li class="nav-heading">Tutorials</li><li class="nav-item"><a href="tutorial-00_Introduction.html">00_Introduction</a></li><li class="nav-item"><a href="tutorial-01_Function_Calls.html">01_Function_Calls</a></li><li class="nav-item"><a href="tutorial-02_Function_Composition.html">02_Function_Composition</a></li><li class="nav-item"><a href="tutorial-03_Table_Operations.html">03_Table_Operations</a></li><li class="nav-item"><a href="tutorial-04_Currying.html">04_Currying</a></li><li class="nav-item"><a href="tutorial-05_Pattern_Matching.html">05_Pattern_Matching</a></li><li class="nav-item"><a href="tutorial-06_Immutable_Tables.html">06_Immutable_Tables</a></li><li class="nav-item"><a href="tutorial-07_Function_References.html">07_Function_References</a></li><li class="nav-item"><a href="tutorial-08_Combinators.html">08_Combinators</a></li><li class="nav-item"><a href="tutorial-09_Expression_Based.html">09_Expression_Based</a></li><li class="nav-item"><a href="tutorial-10_Tables_Deep_Dive.html">10_Tables_Deep_Dive</a></li><li class="nav-item"><a href="tutorial-11_Standard_Library.html">11_Standard_Library</a></li><li class="nav-item"><a href="tutorial-12_IO_Operations.html">12_IO_Operations</a></li><li class="nav-item"><a href="tutorial-13_Error_Handling.html">13_Error_Handling</a></li><li class="nav-item"><a href="tutorial-14_Advanced_Combinators.html">14_Advanced_Combinators</a></li><li class="nav-item"><a href="tutorial-15_Integration_Patterns.html">15_Integration_Patterns</a></li><li class="nav-item"><a href="tutorial-16_Best_Practices.html">16_Best_Practices</a></li><li class="nav-item"><a href="tutorial-README.html">README</a></li><li class="nav-heading"><a href="global.html">Globals</a></li><li class="nav-item"><span class="nav-item-type type-member">M</span><span class="nav-item-name"><a href="global.html#callStackTracker">callStackTracker</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#debugError">debugError</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#debugLog">debugLog</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#executeFile">executeFile</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#initializeStandardLibrary">initializeStandardLibrary</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#interpreter">interpreter</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#lexer">lexer</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#main">main</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#parser">parser</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#readFile">readFile</a></span></li><li class="nav-item"><span class="nav-item-type type-function">F</span><span class="nav-item-name"><a href="global.html#run">run</a></span></li> +</nav> + +<div id="main"> + + <h1 class="page-title">16_Best_Practices</h1> + + + <section> + +<header> + +</header> + +<article> + <h1>Operator Spacing Best Practices</h1> +<h2>Why Spacing Matters</h2> +<p>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.</p> +<h2>Minus Operator Spacing</h2> +<h3>Unary Minus (Negative Numbers)</h3> +<p>Unary minus works without parentheses and requires no leading space:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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)) */ +</code></pre> +<h3>Binary Minus (Subtraction)</h3> +<p>Binary minus requires spaces on both sides:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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) */ +</code></pre> +<h3>Legacy Syntax (Still Works)</h3> +<p>Legacy syntax continues to work for backward compatibility:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ CORRECT - Legacy syntax still works */ +(-5); /* negate(5) - explicit grouping */ +f (-5); /* f(negate(5)) - explicit grouping */ +5-3; /* subtract(5, 3) - legacy fallback */ +</code></pre> +<h3>Complex Expressions</h3> +<p>Complex expressions with mixed operators work correctly:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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) */ +</code></pre> +<h2>General Operator Spacing</h2> +<h3>Binary Operators</h3> +<p>All binary operators should have spaces around them:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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) */ +</code></pre> +<h3>Comparison Operators</h3> +<p>Comparison operators require spaces:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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) */ +</code></pre> +<h3>Logical Operators</h3> +<p>Logical operators require spaces:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ CORRECT - Logical operators with spaces */ +true and false; /* logicalAnd(true, false) */ +true or false; /* logicalOr(true, false) */ +true xor false; /* logicalXor(true, false) */ +</code></pre> +<h3>Unary Operators</h3> +<p>Unary operators (except minus) don't require special spacing:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ CORRECT - Unary operators */ +not true; /* logicalNot(true) */ +not false; /* logicalNot(false) */ +</code></pre> +<h2>When to Use Parentheses</h2> +<h3>Explicit Grouping</h3> +<p>Use parentheses when you need explicit control over precedence:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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 */ +</code></pre> +<h3>Complex Expressions</h3> +<p>Use parentheses to make complex expressions more readable:</p> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ CORRECT - Complex expressions with parentheses */ +(-5 + 3) * 2; /* multiply(add(negate(5), 3), 2) */ +(-5) * (3 + 2); /* multiply(negate(5), add(3, 2)) */ +</code></pre> +<h2>Common Patterns</h2> +<h3>Function Calls with Negative Numbers</h3> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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}) */ +</code></pre> +<h3>Comparisons with Negative Numbers</h3> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ CORRECT - Comparisons with negative numbers */ +-5 >= 0; /* greaterEqual(negate(5), 0) */ +-5 < 0; /* lessThan(negate(5), 0) */ +is_negative -5; /* is_negative(negate(5)) */ +</code></pre> +<h3>Arithmetic with Mixed Operators</h3> +<pre class="prettyprint source lang-plaintext"><code>/* ✅ 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) */ +</code></pre> +<h2>Best Practices Summary</h2> +<h3>Do's</h3> +<ul> +<li>✅ <strong>Use spaces around binary operators</strong>: <code>5 - 3</code>, <code>5 + 3</code>, <code>5 * 3</code></li> +<li>✅ <strong>Unary minus works without parentheses</strong>: <code>-5</code>, <code>f -5</code></li> +<li>✅ <strong>Use parentheses for explicit grouping</strong>: <code>(-5)</code>, <code>(5 + 3) * 2</code></li> +<li>✅ <strong>Use spaces around comparison operators</strong>: <code>5 = 3</code>, <code>5 < 3</code></li> +<li>✅ <strong>Use spaces around logical operators</strong>: <code>true and false</code></li> +</ul> +<h3>Don'ts</h3> +<ul> +<li>❌ <strong>Don't omit spaces around binary operators</strong>: <code>5-3</code>, <code>5+3</code> (legacy fallback)</li> +<li>❌ <strong>Don't add spaces after unary minus</strong>: <code>- 5</code> (legacy fallback)</li> +<li>❌ <strong>Don't use inconsistent spacing</strong>: <code>5- 3</code>, <code>5 -3</code> (legacy fallback)</li> +</ul> +<h3>When in Doubt</h3> +<ul> +<li><strong>Use spaces around binary operators</strong> - it's always correct and more readable</li> +<li><strong>Unary minus works without parentheses</strong> - <code>-5</code> is the preferred syntax</li> +<li><strong>Use parentheses for explicit grouping</strong> - when you need to control precedence</li> +<li><strong>Follow functional language conventions</strong> - spaces around operators are standard</li> +</ul> +<h2>Examples in Context</h2> +<h3>Data Processing</h3> +<pre class="prettyprint source lang-plaintext"><code>/* 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) */ +</code></pre> +<h3>Validation Logic</h3> +<pre class="prettyprint source lang-plaintext"><code>/* 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 */ +</code></pre> +<h3>Mathematical Expressions</h3> +<pre class="prettyprint source lang-plaintext"><code>/* 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) */ +</code></pre> +<h2>Key Takeaways</h2> +<ol> +<li><strong>Spacing distinguishes operators</strong> - unary vs binary minus</li> +<li><strong>Unary minus works without parentheses</strong> - <code>-5</code> is preferred</li> +<li><strong>Binary operators need spaces</strong> - <code>5 - 3</code>, <code>5 + 3</code>, <code>5 * 3</code></li> +<li><strong>Legacy syntax still works</strong> - but spaces are recommended</li> +<li><strong>Parentheses for explicit grouping</strong> - when you need control</li> +<li><strong>Follow functional conventions</strong> - spaces around operators are standard</li> +</ol> +<p><strong>Remember</strong>: Proper spacing makes your code more readable and follows functional language conventions! 🚀</p> +</article> + +</section> + +</div> + +<br class="clear"> + +<footer> + Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a> on Tue Jul 29 2025 23:15:00 GMT-0400 (Eastern Daylight Time) using the Minami theme. +</footer> + +<script>prettyPrint();</script> +<script src="scripts/linenumber.js"></script> +</body> +</html> \ No newline at end of file |