Styleguide
NickyMeuleman opened this issue · comments
To keep the formatting/code style consistent as more people contribute to this project, I propose automating (part of) it.
I asked if there was a styleguide on Discord, and @BenDMyers said:
Not yet - but I’d say ideally use tabs and semicolons.
This (partial) automation can be done with tools like:
Prettier for formatting.
Possibly
- ESLint for JavaScript linting
- Stylelint for CSS linting
- with stylelint-config-recommended that turns on only rules for possible errors.
If linting tools are used, it is important to use the matching *-config-prettier (like stylelint-config-prettier for stylelint) to prevent conflicts between the linter and Prettier. Leaving all formatting concerns up to Prettier.
I'd be happy to implement the tools while we discuss what rules to apply here.
Hey, @NickyMeuleman! This is a great idea! Are you good with me assigning this issue to you?
Please do!
@NickyMeuleman Assigned!
For my two cents' worth, here are two standardizations I'd like to really encourage and why:
- Tabs for indentation: The ability to set your own preference tab width is hugely important for folks with low vision who may, for instance, zoom in a lot and set a small tab width so lines don't run off screen, or set a wide tab width so lines don't blur together.
- Use semicolons: This project already has a few immediately-invoked function expressions, which are some of the few times where semicolons are basically required, so requiring semicolons everywhere ensures we don't break our IIFEs.
Beyond that, here are some of the conventions I've already been using which we maaaay consider adopting for minimal changes, but which I'm not married to:
- Single quotes for strings
- No extra spaces for inline objects and destructuring (so
{beep: 'boop'}rather than{ beep: 'boop' })
TIL IIFE's need semicolons. Thought I was able to be rid of those forever, guess not!
Commenting this here because it's relating to the higher-level issue, and not the specific implementation of the PR.
Should JSDOC comments be linted?
It can make writing those a bit easier.
For example: I have 0 experience with those, so I'd like my editor to go "that's not a valid JSDoc, you need to add ***"
edit: comment for myself so I remember: explore eslint-plugin-jsdoc
Oh, interesting - I hadn't considered linting JSDoc comments, @NickyMeuleman, but I'd be open to it if you feel like it would provide benefits for folks who are new to writing them!
My strongest feeling is that linting should enable folks, not hinder them - so where possible, I prefer linting that serves as a helpful guide, rather than a restrictive tool you have to fight against. This seems like one case where it could be a helpful guide.
Super agree!
I only enabled a thin foundation for rules of linting tools in the PRs.
The rules that are enabled lint against "possible errors", those shouldn't include preferences like always using function brackets or not. (wrote "shouldn't" because I haven't checked them all).
Similar question: HTML linting?
I haven't used it before, but I found HTMLlint, and the rules seem like they fit the "prevent errors" pattern instead of the "enforce preferences" one.
Oooh - every single one of those HTMLint rules seems good. I vote yes, let's add HTMLint to the tooling.
TIL Markdown is inconsisent with hard tabs (which probably why Prettier uses spaces for indentation too).
edit: Aha, it correctly uses tabs inside codeblocks automatically, neat. Automatic formatting of code in markdown!
Thoughts on using a linter for Markdown (like MarkdownLint)? To help catch logical errors (like non-incrementing # headers by skipping a level)
Apparently there is one rule that should be disabled if used together with prettier.
I'm good with adding a Markdown linter!