Script SpringsISSUE #4 of 29

comments · single · multi · jsdoc

SparkyVSNaN the Trickster

Sparky saysComments document code: // for one line, /* */ for blocks, /** */ for JSDoc.

// line comment and /* block comment */ are ignored at runtime. JSDoc (/** … */ with @param/@returns) documents functions and powers editor tooltips and type hints. Comment the why, not the obvious what.

Power-ups you unlock

// single-line · /* */ multi-line
/** JSDoc */ documents params & returns
Editors read JSDoc for hints
Explain why, not what the code obviously does

NaN the Trickster attacks — common mistakes

Comments restating the code verbatim
Stale comments that no longer match the code
Commenting out big blocks instead of deleting/versioning

Boss battleAdd a JSDoc comment to a function describing its parameter and return.

Example code

<!doctype html><html><head><meta charset="utf-8"></head>
<body style="background:#06040d;color:#e6e0ff;font-family:monospace;padding:20px"><pre id="o"></pre>
<script>/** double a number @param {number} n @returns {number} */
function double(n){ return n*2; } // why: shared helper
document.getElementById('o').textContent = double(21);</script></body></html>

▶ Open the interactive comic issue

‹ Syntax · Statements · Expressions Variables · Var · Let · Const ›