best-practices

Billions of lines of software code are written every single day. Some by beginners, some by hobbyists, and some by experienced professionals. However, no matter which category of a developer is writing software, there are many that do not write high-quality software. They write code that may work but isn’t easily readable or easily maintainable. It normally also does not contain good comments that help other developers easily understand the code. The software quality of these developers is quite poor and could really need some automated enforcement of better code quality. This post will show how to use Code Climate to enforce better software quality from every developer.

---

Check out our related YouTube video:

---

Intro To Code Climate

Two software engineering team leads founded Code Climate in 2011 and were trying to solve the issue of poor software quality. They wanted to create a product that helped enforce code quality for all software teams that desired high software quality. They created a platform that can hook into GitHub’s continuous integration (CI) and continuous delivery (CD) workflows. This CI/CD hook can block any low-quality code from reaching customer-facing products. This hook runs a customizable list of checks against the code base before it ships to customers.

NOTE: As of June 2022, Code Climate only works with GitHub

Configuring Code Climate Via Browser

While signing up for an account with Code Climate, you can add your GitHub organization and/or repositories to your account. You can then add some initial configuration via the UI if desired. Click on one of your newly added repos, and then:

• Repo Settings > Integrations – Set up a Slack, HipChat, or Campfire channel for notifications
• Repo Settings > Integrations – Set up an integration to create tickets/issues in Asana, JIRA, GitHub, or Lighthouse when new issues are discovered
• Repo Settings > Integrations – Setup integration with Gitlab to update pull requests statuses
• Repo Settings > GitHub – Setup option to have Code Climate add comments to GitHub Pull Requests and PR status updates
• Repo Settings > Maintainability – Select which types of maintainability checks you wish to have run against your code. (these can be configured with more detail via a configuration file discussed later)
• Repo Settings > Test Coverage – This section will allow you to enforce a certain amount of test coverage for your code before allowing it into production. You can set options for desired coverage for specifically new changes or as the whole project.
  • This section also has the Test Reporter ID value you use in your CI/CD pipeline scripts to upload code coverage results
• Repo Settings > Plugins – Allows for integration with additional style, linting, and security static analysis tools not offered directly from Code Climate
• Repo Settings > Exclude Patterns – Not all files and folders need to be scanned for code quality. Some are just configuration files or third-party packages that you cannot modify or control. You can add these files and directories here
• Repo Settings > Badges – You can find badges to place on your website in our repository’s README to show the quality and test coverage of your code base. They offer multiple different forms of the badges (HTML, Markdown, Textile, etc) so you can add them to multiple places

There Is Another (And Better) Approach

The easiest and quickest way of configuring Code Climate is shown above. However, you have to manually configure each repository separately in the UI. This can lead to inconsistencies across your projects. It is time-consuming to go through and set up all of the above settings for each repository. On top of that, there is no way to keep track of any changes in the configuration settings. This can make it difficult to track down any issues that may arise after making any changes in the UI. Let’s look at a better approach that can solve all of these issues.

Configuring Code Climate Via Configuration Files

A much better way of handling the configuration of most repositories is to create a Code Climate configuration file inside each repository.  This will allow for greater control of almost every aspect of your Code Climate configuration. You control which checks are utilized, which versions to use, as well as the details of each check using this option.

First, create a .codeclimate.yml or .codeclimate.json file in the root of your repository.

There are 5 root sections available to add to a Code Climate configuration file. They are version, prepare, checks, plugins, and exclude_patterns. See the template below:

- version: The currently supported version is "2"
- prepare: Actions to perform before analysis begins
  - fetch: Remote files to fetch (files are placed relative to the repo's root directory)
  - url: URL to fetch
    path: destination relative to repo's root directory
- checks: Configuration of maintainability checks
  - <name>
    - enabled: true|false
    - config: check configuration
- plugins: Enable optional engines to run in addition to your analysis
  - <name>
    - enabled: true|false
    - channel: alternate channel to use (stable is default)
    - config: plugin configuration
- exclude_patterns: Exclude files and/or directories from analysis
  - <pattern>
  - <pattern>

All default maintainability checks are enabled by default. If you wish to disable any of the default checks, you would need to specify that in your config file.

Customizing Default Checks In The Configuration File

For example, if you didn’t want to have Code Climate perform the  Complex Logic checks on your code, you would add the following to your configuration file:

.codeclimate.json
----------------------
{
  "version": "2",
  "checks": {
    "complex-logic": {
      "enabled": false
    }
}

.codeclimate.yml
---------------------
version: "2"
checks:
  complex-logic:
    enabled: false

Now that we have disabled any or all default checks offered by Code Climate, let’s see how we can customize the configuration of some of these default checks. Let’s say you had a legacy project that had some methods that had more than 25 lines of code. By default, Code Climate will flag all methods with more than 25 lines of code. This leads to code constantly being flagged for maintainability and quality issues. However, we can adjust this setting in the configuration file to any value we choose. Let’s update it to be 50 lines of code.

.codeclimate.json
----------------------
{
  "version": "2",
  "checks": {
    "method-lines": {
      "config": {
         "threshold": 50
      }
   }
}

.codeclimate.yml
---------------------
version: "2"
checks:
  method-lines:
    config:
      threshold: 50

You can update the configuration settings for the majority of checks and plugins available in Code Climate. The full list of plugins available for Code Climate is found here.

Adding Plugins In The Configuration File

To add plugins to your configuration, just add it to the plugins section of your config file with enabled: true like such:

.codeclimate.json
----------------------
{
  "version": "2",
  "checks": {
    "eslint": {
      "enabled": true
    }
  }
}

.codeclimate.yml
---------------------
version: "2"
checks:
  eslint:
    enabled: true

Customizing Plugins In The Configuration File

What about if you don’t wish to run the latest version of the eslint plugin for some reason? You can tell Code Climate to use a different version by supplying the desired version for the channel field like so:

.codeclimate.json
----------------------
{
  "version": "2",
  "checks": {
    "eslint": {
      "enabled": true,
      "channel": "eslint-6"
    }
  }
}

.codeclimate.yml
---------------------
version: "2"
checks:
  eslint:
    enabled: true
    channel:"eslint-6"

Another option in the configuration file is to disable any plugins added. The following is all you need to do to disable a plugin without removing it completely from the file:

.codeclimate.json
----------------------
{
  "version": "2",
  "checks": {
    "eslint": {
      "enabled": false,
      "channel": "eslint-6"
    }
}


.codeclimate.yml
---------------------
version: "2"
checks:
  eslint:
    enabled: false
    channel:"eslint-6"

Customizing Files And Directories To Exclude

Excluding directories and files is as easy as adding a list of exclusions for Code Climate to ignore in your repository. These exclusions use regular expression syntax to be able to match almost any combination of characters you can think of. Each Code Climate project comes with a default list of directories and files to exclude. However, you can override this by providing your own list if desired. The default items are:

config/
db/
dist/
features/
**/node_modules/
script/
**/spec/
**/test/
**/tests/
Tests/
**/vendor/
**/*_test.go
**/*.d.ts

The defaults will most likely not completely fit a majority of projects, so most repositories will need to add custom entries. However, this default list is a good starting point. You will almost always wish to exclude unit/integration/E2E test directories, third-party packages directories, configuration files, and build artifacts. 

Looks like we have our first Code Climate configuration file all set up. Now let’s focus our attention on how to get this working in our GitHub workflow to enforce allowing only high-quality code into the production code bases.

---

Integrating Code Climate With GitHub

Now that we have our Code Climate configuration file sorted out and set up the way we want, we need to set up Code Climate on GitHub. We want to enforce good code quality, right? So we’ll need to set up protection checks on our production branch(es). 

NOTE: The following steps can also be done via configuration files in your repository, but that is a complete topic of its own. Check out the GitHub Settings app in the GitHub marketplace to learn more about that option.

To add branch protection, go to your repository branch settings in GitHub (e.g. https://github.com/[your org]/[your repo]/settings/branches).

• Under Branch protection rules click on Add Rule
• For Branch name pattern enter the name of your production/release branches (see this page for the format to be used to match multiple branches)
• Select Require pull request before merging
  • Select Dismiss stale pull request approvals when new commits are pushed
• Select Require status checks to pass before merging
  • Select Require branches to be up to date before merging
  • Select the status checks from Code Climate you want to be enforced before allowing merges into production. If there are not any status checks yet, you will need to commit your Code Climate config file and push it to GitHub. It should then show up in this list

Your branch setup should now look similar to the following:

Now, any code being merged into production code bases needs to pass all of the Code Climate checks before GitHub allows it to be merged!

---

Conclusion

Congrats! Now you have set up your repository to enforce much higher code quality! It will save your team time and effort as developers do not have to spend time reviewing bad PRs multiple times just to improve the code quality or test coverage. Code Climate will show a failure on the PR and thus the reviewer and developer already know there are changes to be made.

Leave a comment below to let me know if this helped or if this post can be improved even more in some way. Or just drop a comment suggesting a new topic you want me to post about. Also don’t forget to give us a follow on Facebook, Twitter, LinkedIn, and Instagram!