JavaScript style guide for documentation PRs

@zachleat,

Can we drum up a quick style guide for vanilla JS code examples? I’m willing to forego my (otherwise highly opinionated) personal style for a standard.

I can mimic what’s already there, but it’d be good to establish something formally—for consistency within the docs (if not also the codebase). Here are the major categories I’m thinking we could use some clear ground rules:

• Ternary operators v. conditional statements?
• Semicolon?
• Closures?
• Explicit return statements?
• var v. const and let?
• Arrow functions v. declarations v. expressions?
• When and when not to cache variables
• Classes v. exports.render
• Comments and/or JSDoc blocks?
• import v. require()
• this
• Others?

I’m convinced more folks would reach for the vanilla 🍦 if they had more examples in the docs—and I wanna help.

[Ryuno-Ki]

Looking into that right now (but @matt-auckland was faster with https://github.com/11ty/11ty-website/commit/3a0ce3b1535d7d220091df86bb20a9faff40c916 ):

• Use semicolons
• Use double quotes over single quotes to wrap basic strings
• Use backticks when leveraging template stings => https://eslint.org/docs/rules/prefer-template ?
• Use an explicit return when returning a string or an object, but not a function (e.g., setTimeout()) => https://eslint.org/docs/rules/consistent-return ?
• Do not include a space between function and () when declaring an anonymous function => https://eslint.org/docs/rules/space-before-function-paren
• Use const and let, not var => https://eslint.org/docs/rules/no-var
• Use arrow functions only when demonstrating them as a use case, to avoid mistakenly breaking this binding for shortcodes, filters, transforms, etc. => https://eslint.org/docs/rules/prefer-arrow-callback
• Use classes when only when demonstrating them as a use case, otherwise opt for the shorter, more modular exports.data = {}; exports.render = function() {}; pattern available since 0.9.0, thanks again @jakearchibald! (Okay, I added this one, but there are no examples in the docs of this option, and I strongly believe it should be the default format in the docs for reasons too numerous and heartfelt for the purposes of this list.) => No ESLint rule?
• When there are multiple methods within a function (e.g., a class), place a blank line between each method, but not around them (i.e., do not a blank line at the beginning or end of the wrapping function) => https://eslint.org/docs/rules/space-before-blocks
• Use the ternary operator inside template strings, otherwise use good judgment for if statements when it may aid readability (This is a guess, the ternary operator makes more sense than wrapping conditional logic in an IIFE inside template strings.) => https://eslint.org/docs/rules/no-unneeded-ternary ? (Or perhaps regarding nested ternaries?)
• Avoid multiline comments inside code examples, instead keep the code examples themselves short and instead explain what’s going on in the body of the page; when especially helpful, place single line comments on the line above the code to which they apply => https://eslint.org/docs/rules/line-comment-position

If you agree, I’d fill a PR with those rules added.

[Ryuno-Ki]

Shoot, totally forgot about this! Yes, I’m still interested. Thanks for the reminder!