JavaScript style guide for documentation PRs

[reubenlillie]

@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.

[reubenlillie]

@zachleat, since the request for more vanilla JS doc examples came up in 11ty/eleventy issue 921 do you think it'd be a good idea to add this to the Eleventy 1.0 project board?

[Ryuno-Ki]

Um, JSDoc comments are most likely written by me if they document the signature :-) Willing to chime in, once https://github.com/11ty/eleventy/pull/720 gets merged.

[reubenlillie]

@Ryuno-Ki, Ha! I was referring both to JSdoc, the automation app, and the notion of JS examples in the docs. Sorry for any confusion. I use JSDoc.app extensively on my own sites too. In any case, I want to help make sure the JS examples are as consistent and useful as possible.

[Ryuno-Ki]

Same here :-) However, I'd rather not have big PRs but a set of small ones. I defer to @zachleat to decide when to move forward on this topic. I'm aware, that documentation is something, many developers don't like to deal with. But in my opinion, it is too important to neglect.

[reubenlillie]

@Ryuno-Ki, of course. I was imaging making separate PRs for each snippet on the site, individual pages of them at the most. @zachleat?

[reubenlillie]

Here’s my best attempt at @zachleat -style JavaScript a la the docs, at least for code snippets:

• Use semicolons
• Use double quotes over single quotes to wrap basic strings
• Use backticks when leveraging template stings
• Use an explicit return when returning a string or an object, but not a function (e.g., setTimeout())
• Do not include a space between function and () when declaring an anonymous function
• Use const and let, not var
• Use arrow functions only when demonstrating them as a use case, to avoid mistakenly breaking this binding for shortcodes, filters, transforms, etc.
• 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.)
• 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)
• 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.)
• 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

How’d I do?

[Ryuno-Ki]

Do not include a space between function and () when declaring an anonymous function

I'm not sure, where I found that trick, but it's a neat hack: By adding the space, you can easily find the declaration of a function instead of all its invocations. I'd suggest to keep it.

[reubenlillie]

@Ryuno-Ki,

I'm not sure, where I found that trick, but it's a neat hack: By adding the space, you can easily find the declaration of a function instead of all its invocations. I'd suggest to keep it.

Yes. I use the space in my own code. But, like I said, I’m foregoing my own style for consistency within the docs.

[Ryuno-Ki]

Hm, I'm wondering, whether we could put together an ESLint config to ease with an agreed upon style convention …

[reubenlillie]

@Ryuno-Ki, do you know how to/want to make that kind of config?

[Ryuno-Ki]

Sure, why not? Would you be willing to review it then?

[reubenlillie]

Absolutely.

[reubenlillie]

@Ryuno-Ki, are you still interested in the idea of an ESLint config of some kind? I'm still happy to review.

[Ryuno-Ki]

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

[Ryuno-Ki]

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

• [x] Use semicolons
• [x] 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.