Two Awesome Tools to Bring Strong Coding Conventions to your Team

Diversity in code is introduced by diversity of background of the team’s developers. Changes in style can cause headaches, you don’t want to ask yourself: is this function camelCase or snake_case?

Linters help checking that, and also ensure that your code follows the community’s conventions. They allow rule-by-rule configuration to match your team’s habits and goals. And you can still let linting errors pass when you think you have to assume it, or tag them as invalid when the robot is wrong (robots are (almost) never wrong). It is an important part of our git flow (read more about that here, in French).

Cylon raider, wait, no, a linter checking your code for typos (illustration)

Being assured that your code follows your writing standards help maintenance, code review, onboarding of the new devs and gives one more tool to help juniors progress. It’s an easy first thing to set up to start working on code quality.

In this article, we’ll cover two tools to work with linters:

• overcommit to install git hooks locally, preventing commits with linting errors to end up in a pull request
• codeclimate quality to add reports on pull requests, get statistics and follow trends on the long run

With that being said, let’s dive in!

Overcommit overview and setup

As previously mentioned, overcommit allows you to setup git hooks preventing commit or push when a check fails. Checks include push on protected branches, format of commits messages, linters, etc. In this chapter, we’ll focus on RuboCop.

Overcommit being grumpy about an empty commit message (real example this time)

Install the gem and the hooks

If you use bundler, add this to your gemfile

group :development do
  […]
  gem 'overcommit', require: false
  […]
end

If you don’t, simply install the ruby gem $ gem install overcommit.

It’s the same thing to install RuboCop, if you haven’t installed it already. Add RuboCop to your Gemfile (if it’s not already there)

group :development do
  […]
  gem 'overcommit', require: false
  gem 'rubocop', require: false
  […]
end

Or install it via $ gem install rubocop.

Then run $ overcommit --install in your project to install the git hooks. Simple, right? Yeah, well, as overcommit doesn’t guess which languages you use and which linters you wish to install, you have to add a little…

Configuration

Create a file called .overcommit.yml in your project root directory. Check the default configuration and overload it in your own file. Here’s an example to enable RuboCop:

PreCommit:
  RuboCop:
    enabled: true
    requires_files: true

You have to sign the configuration file each time it changes, so now run $ overcommit --sign. This makes sure you agree with every change made on your machine concerning overcommit.

That’s it! Now every ruby files commited will be checked by RuboCop.

Bad line no commit! — RuboCop

Spread the word to your teammates by adding $ overcommit --install and $ overcommit --sign to README.md!

Skipping hooks

Imagine you are refactoring some old code. You made it better, but it’s not perfect and the timebox you’ve given yourself runs out. The linters may be unhappy with the code you are trying to submit. Well, you can tell overcommit to skip some checks to let you commit. To do this, you can use the SKIP env var.

Refactoring some old code and skipping linters (illustration of the developper feelings)

For example, $ SKIP=RuboCop git commit if you wish to skip RuboCop for a commit. Separate checks with a comma if you want to skip multiple things, e.g. $ SKIP=RuboCop,Reek git commit.

But you still want to see when a coworker skipped an important check. That’s why we use…

Code Climate Quality overview and setup

« Quality by Code Climate provides automated code review for test coverage, maintainability and more so that you can save time and merge with confidence. » (NB: this article is not affiliated with code climate in any way). It usually works using github webhooks and integrates in your pull requests. So you’ll have a nice tool to automatically review pull requests, that lets reviewers focus on the important things or have access to documentation. Plus you’ll have some nice progress graphs of the state of your app for the long run :)

Code Climate being unhappy with a commit

Code Climate will make a report on every pull requests with a nice summary of new and fixed issues in your changes. Apart from the usual linters and code smellers, a tool I really like in Code Climate is the duplication engine, capable of detecting similar code anywhere else in your app. Very useful to keep your application DRY! (DRY is part of our manifesto, read more about it here, in French)

One more good feedback when reducing technical debt!

Improving code coverage feels even better now

Setting up is pretty easy, and happens mostly in your web browser. Advanced options require a .codeclimate.yml file in your project root, but you can start without it. The official guide is pretty good, so there’s no point in copying it here.

How do we use overcommit and Code Climate Quality together

Our configuration allows ourselves to be more strict locally with overcommit, and being more flexible on Code Climate. For example, overcommit runs a code smell detector called Reek, which is not enabled on Code Climate (although it is available). Also specs are ignored on code climate, but overcommit will check them.

With Code Climate Quality in place, overcommit becomes mostly a productivity tool: no need to push your changes and wait for the robot to check them. No more “Fix rubocop” commits that makes the commit-per-commit reviews complicated.

Keep humans code reviews

We use these tools to automate part of the review process and keep strong code quality conventions on the team. These tools are great, there are probably other great tools outside in the wild, just pick the one that is most suitable to you.

Automated review does not replace human code review. It is possible to write code with no linting errors or code smells detectable by robots, but that makes absolutely no sense. You can also have two files to do basically the same thing, may be because you are A/B testing, which creates duplication that can’t be detected by a robot. It also helps to improve your bus factor.

If you wish to have your code reviewed by humans and robots, you can apply here to work with us!

Captain Contrat recrute !