A Practical Guide to Introducing Linting to Your Engineering Team
Over the years, I’ve had the wonderful opportunity to work with many great teams to improve application code quality, readability and maintainability. One of the most effective ways the teams I’ve worked with upped our game on this front is through the use of linters.
This article will explain the benefits of linters in a team environment and how to best sell the idea to management and your peers.
What is Linting? Why should your team do it?
A linter is a tool that performs static code analysis in order to maintain consistent code style, prevent code cruft (e.g. unused local variables or unreachable code) and more complex rules like performance optimizations when there are multiple ways to achieve the same result.
By agreeing on a consistent set of code style rules, preferably one that is popular in the community, your team will avoid unnecessarily complex code reviews that are mostly just formatting changes. Many linters offer customization of the rules they enforce, so you can tailor your linter to your specific team and their preferences.
Consider Rubocop’s Performance/InefficientHashSearch cop as an example. This type of performance linter is useful for high-throughput method calls and ensuring your team is writing the most efficient code possible.
Getting Buy-In From the Team
There are a couple of stakeholders you’ll need to consider when convincing your team to start using linters. You’ll need to convince your engineering leadership as well as your peers that this is a worthwhile endeavor.
One of my favorite lines from Clean Code by Robert C. Martin describes the relationship between engineering leadership and the teams they lead.
Most managers want good code, even when they are obsessing about the schedule. They may defend the schedule and requirements with passion; but that’s their job. It’s your job to defend the code with equal passion.
Linters help your team write clean code quickly — so this satisfies both party’s concerns! So how do you sell linting to leadership and your peers? Here are the main points to drive home:
- Linters significantly increase code quality, and can be set up to do so automatically with minimal up-front investment.
- Your team’s code will take on consistent style/form, which will make code reviews quicker and more effective. No more comments wasted on “this should be indented 2 more spaces!”
- Any current debt you have on this front can be fixed quickly using the linter’s auto-fix functionality.
- The ongoing benefits of linting will actually speed up development, not slow it down.
Getting Started — First Steps
Before you go adding a linter to your project, enable all possible rules, auto-fix everything and ship it, there are some important things to keep in mind.
Start small — start with one PR that introduces the linter and the configuration file. Many linters also support excluding certain files that might be particularly problematic. Rather than try to fix all your “linter debt” all at once, try the following process:
- Start by identifying all the rules you’re currently breaking. Add these rules to your linter config to disable these checks. Here’s an example for what we used with Rubocop:
- Open your first pull request to add the linter and the config to your repo with the proper linters disabled.
- Slowly enable similar linters and running the linter auto-fix tool. This will result in many smaller pull requests to pay down this debt instead of one massive shock to the repository.
- Carefully review these changes, as linter auto-fix functionality is not foolproof. Some violations also won’t be able to be auto-fixed, and it’s important to make sure your code still produces the same output.
Your teammates will thank you when they’re not stuck in rebasing hell because you decided to fix all your linter issues all at once. Which pull request would you rather review?
1 Pull Request Auto-fixing All Violations at Once
Showing 1,607 changed files with 21,393 additions and 21,411 deletions.Numerous Small Pull Requests Auto-fixing Specific Violations
Showing 123 changed files with 259 additions and 315 deletions.
Showing 12 changed files with 15 additions and 17 deletions.
Showing 71 changed files with 104 additions and 115 deletions.
Ongoing Workflow — Maintaining the Habit
At Compass, we use pre-commit hooks which run our linters on the subset of files that have actually changed. This ensures that code is clean as early as possible in the development process.
Now, sometimes we may be in a hurry and we don’t want to fix all our violations, but we want to make sure we’ve pushed up our work in progress in case our laptop gets smashed or eaten by a dog.
We want to ensure that developers don’t inadvertently merge these violations into our main branch, leaving that mess for the rest of the team to clean up. So — how can we prevent that?
Add your linter to your automated CI tool. We use Travis CI, and one of our passing test suite requirements is all happy linters! This helps ensure that any code that’s getting merged into our main branch is clean, regardless of individuals skipping linters locally or not having pre-commit hooks set up properly.
Hopefully you’ve learned a little bit more about linters, and more importantly, how to start using them without your team wanting to ring your neck. Please post any stories your team has faced on this front below!
There’s one simple question to help you decide if you should be using a linter: Do you write code? If you answered yes, then you should be using a linter!
Compass is looking for experienced software engineers who are passionate about solving complex problems with code. We’ve taken a novel approach to building business software — focus on the end user — and it’s been working! Our users love us. Come help us build a product that makes the real estate process easy and rescue 10,000s of people from the jaws of clunky, outdated software.
