As programmers part of our daily job is writing clean, simple and readable code. Writing a program is a lot like writing an essay - your message is more convincing when it's accompanied by proper grammar and punctuation. When you're programming you should follow the same principle because of two reasons. One day you might be assigned to work with other people and support your (and their) code for long periods of time. Or even better - you'll have to read, understand and maintain someone else's code!
So what programming principles are we talking about?
- Keep programs and methods short and manageable
- Use language-specific idioms
- Use straightforward logic and flow-of-control
- Avoid magic numbers; instead, give them meaningful symbolic names
- Use meaningful names for ... pretty much everything
Talking about pretty much everything - you should also check your spelling. And by saying that I don't mean go get a spelling dictionary, but rather follow code and style guides of the language you're using. In some cases this is easier said than done and this article is going to cover one specific case.
A new project was started, we were very happy and enthusiastic, sprints were crushed and few weeks later it was time to refactor (yes, we're one of those teams that do that). As a result we ended up with simpler and better code, but in the making we had one big problem - everyone had a different understanding of code formatting (how to arrange function arguments, when to break new lines, usage of single and double quotes, etc.) and we struggled to unify the format all around.
Solution? Prettier! There's no reason for anyone to spend any time and mental energy formatting their (and his teammates') code.
What is prettier
Adding prettier in your project
There are few ways to introduce prettier in your project.
The easiest one is adding an integration to your favourite text editor. Most common editors already have a package written, but if you don't find yours in the list feel free to develop one and add it here. Next step would be adding some options that differ from default ones. Then all of your current (and future) teammates will have to do this. Something smells fishy. I see repeatable action with a lot of room for errors (everyone has their own prettier settings).
We can do better
To avoid PRs (pull requests) with 10 lines of new logic and 150 lines changed because of different setting in you colleague's editor we can write a simple
bash script (bear with me, I also get scared every time I hear/see
bash) that will prettify all files you've changed before commiting them:
#!/bin/bash # Apply prettier to all changed (staged or unstaged) files git diff \ --name-only HEAD \ | grep '\.js\|\.jsx\|\.ts\|\.<any-other-extension-you-need>\?$' \ | xargs <path-to-your-prettier-executable> \ --write \ --print-width 80 \ --tab-width 2 \ --<more-and-more-options>
Something to note here is the
--write option. By using it one allows prettier to edit files directly! Without it you'll end up with pretty code pasted in the terminal.
To avoid explicitly specifying all settings in every bash file you use prettier you can add
.prettierrc file (or symlink) in JSON or YAML format in the folder from which the bash script is being executed. I like to have control over everything I do, but if you prefer you can add a pre-commit hook that runs the script when you do
.prettierrc in place most editors will find the settings and use them, but sadly we don't live in a perfect world and our editor might be messed up or it's one of those days when coffee kicks up with a delay and somehow we push code that's not prettier formatted.
What can we do about the problem above? Write another
bash script of course. This time we're going to execute it on our favourite CI (continuous integration) and make prettier part of our frontend tests. What we want to achieve is run prettier on every file that's supposed to be formatted and assert it's pretty:
#!/bin/bash TEMP="temporary_file_for_prettier" EXIT_CODE=0 for file in $(find <your-source-folder> -name '*.js' -o -name '*.<another-extension>'); do [ -f "$file" ] || continue <path-to-prettier> \ "$file" \ > "$TEMP" diff "$TEMP" "$file" > /dev/null 2>&1 LAST_STATUS="$?" if [ "$LAST_STATUS" -ne 0 ] then echo "$file is not pretty." EXIT_CODE=1 fi done rm "$TEMP" exit "$EXIT_CODE"
This time instead of having
--write we save the output in temporary file which we compare to the original (commited) one. With this step we just unified the code style of our project.
If you're also looking for proper