It sure is nice having a whole codebase that is perfectly compliant to a set of code style guidelines. All the files use the same indentation, the same quote style, the same spacing and line-break rules, heck, tiny things like the way zero’s in values are handled and how keyframes are named.
It seems like a tall order, but these days, it’s easier than ever. It seems to me it’s become a two-tool game:
- A tool to automatically fix easy-to-fix problems
- A tool to warn about harder-to-fix problems
Half the battle: Prettier
Otherwise known as “fix things for me, please”.
Best I can tell, Prettier is a fairly new project, only busting onto the scene in January 2017. Now in the last quarter of 2017, it seems like everybody and their sister is using it. They call it an Opinionated Code Formatter.
The big idea: upon save of a document, all kinds of code formatting happens automatically. It’s a glorious thing to behold. Indentation and spacing is corrected. Quotes are consistent-ified. Semi colons are added.
Run Prettier over your codebase once and gone are the muddy commits full of code formatting cruft. (You might consider making a temporary git user so one user doesn’t look like they’ve commited a bazillion lines of code more than another, if you care about that.) That alone is a damn nice benefit. It makes looking through commits a heck of a lot easier and saves a bunch of grunt work.
As this post suggest, Prettier is only half the battle though. You’ll notice that Prettier only supports a handful of options. In fact, I’m pretty sure when it launched it didn’t have any configuration at all. Opinionated indeed.
What it does support are things that are easy to fix, requiring zero human brainpower. Use double quotes accidentally (uggkch muscle memory) when your style guide is single quotes? Boom – changed on save.
There are other potential problems that aren’t as easy to fix. For example, you’ve used an invalid #HEX code. You probably wouldn’t want a computer guessing what you meant there. That’s better to just be visually marked as an error for you to fix.
That’s where this next part comes in.
The other half of the battle: Stylelint
Otherwise known as “let me know about problem, so I can fix them”.
Stylelint is exactly that. In fact, in that GIF above show Prettier do it’s thing, you saw some red dots and red outlines in my Sublime Text editor. That wasn’t Prettier showing me what it was going to fix (Prettier displays no errors, it just fixes what it can). That was Stylelint running it’s linting and showing me those errors.
Whereas Prettier supports 10ish rules, Stylelint supports 150ish. There is a standard configuration, but you can also get as fine-grained as you want there and configure how you please. David Clark wrote about it here on CSS-Tricks last year.
With these warnings so clearly visible, you can fix them up by hand quickly. It becomes rather second nature.
Getting it all going
These tools work in a wide variety of code editors.
It’s very easy to think “I’ll just install this into my code editor, and it will work!” That gets me every time. Getting these tools to work is again a two-part game.
- Install code editor plugin.
- Do the npm / yarn installation stuff. These are node-based tools. It doesn’t mean your project needs to have anything to do with node in production, this is a local development dependency.
These are intentionally separated things. The meat of these tools is the code that parses your code and figures out the problems it’s going to fix. That happens through APIs that other tools can call. That means these tools don’t have to be rewritten and ported to work in a new environment, instead, that new environment calls the same APIs everyone else does and does whatever it needs to do with the results.
Above is a barebones project in Sublime Text with both Prettier and Stylelint installed. Note the
package.json shows we have our tools installed and I’m listing my “packages” so you can see I have the Sublime Text Plugin jsPrettier installed. You can also see the dotfiles there that configure the rules for both tools.
Don’t let the “js” part mislead you. You could use this setup on the CSS of your WordPress site. It really doesn’t matter what your project is.
Getting more exotic
There is certainly leveling up that can happen here. For example:
- You might consider configuring Stylelint to ignore problems that Prettier fixes. They are going to be fixed anyway, so why bother looking at the errors.
- You might consider updating your deployment process to stop if Stylelint problems are found. Sometimes Stylelint is showing you an error that will literally cause a problem, so it really shouldn’t go to production.
- Stylelint co-creater David Clark introducing Stylelint
- Ashley Nolan on Stylelint, with some interesting history and data
- Stoyan Stefanov on integrating Stylelint and TextMate
- Enforcing CSS Syntax Style
- Artem Sapegin on Why robots should format our code for us
- The chapter from SurviveJS on Code Formatting.
- Mrm: Command line tool to help you keep configuration of your open source projects in sync