Teams of developers need ways of establishing shared practices. I have a philosophy here: linting is better than a style guide, but auto-formatting is better than linting.
In case you don’t know, a linter is a tool that checks code for compliance with a list of rules, reporting any issues it finds as errors. Some of the rules are purely stylistic. But a linter can also prevent actual production bugs by detecting pitfalls inherent to the design of all programming languages. It’s a great tool because it reduces cognitive overhead for authors and reviewers of code, alike. No one needs to internalize the style guide, which frees up everyone to focus on the things that are more unique to your line of business.
But often, it’s irritating to write working, well-tested code only to have to go back and appease the linter. The linter can feel like that friend of yours that is always correcting you with “well, actually….”.
Often times, the fixes can be completely automated, and that’s where formatters come in. Typically, they run automatically as soon as you save a file or commit it to version control. It fixes the issue behind the scenes, and you don’t even have to know or care. I have personally found this to be wonderfully liberating. I used to be very opinionated about the finer points of code style. But when conforming to a style guide takes minimal energy, as is the case with auto-formatted code, I spend my mental energy elsewhere.
A case study
It’s common practice in Git to restrict your line length in your commit messages. The guideline is that the first line should be 50 characters or less, and all other lines should be limited to 72 characters. Long story short, this helps with compatibility with various tools.
In our code review system, we have a warning that is generated when your commit messages are too long, and you have to at least override this warning in order to ship your code. While this helps with quality control, it can also be a bit jarring the first time you encounter the warning. Effectively, this is linting of the metadata of a code change.
Auto-formatting to the rescue
Git provides hooks that allow you to customize its processes. One of them, commit-msg, lets you edit the commit message the user submitted. If you want to enforce this common Git style rule, add this to the .git/hooks/commit-msg of the repo in question:
#!/bin/sh head -n 1 "$1" | grep '.\{50\}' > /dev/null && { echo >&2 Commit failed! Lead line of commit message is $(head -n 1 "$1" | wc -c) chars, but should be shorter than 50. exit 1 } # Hard wrap any long lines in the commit message body. fold -s -w 72 < "$1" > "$1.tmp" mv "$1.tmp" "$1"
100% compliance, zero ongoing effort!
Alan, online. 