How to quantifiably improve maintainability of your code using Code Climate for free on GitHub

As a forewarning, you can definitely follow the Code Climate docs to achieve this: https://docs.codeclimate.com/docs/getting-started-with-code-climate

This is part of a series of articles I’m writing on how I made my personal home page. https://github.com/dsouvage/dsouvage-homepage

Here is the example finished product https://codeclimate.com/github/dsouvage/dsouvage-homepage

Some background requirements:

• a GitHub account and a repository that you want to add
• a repository that is open source(not private) otherwise it will cost money
• 10 minutes

Why is maintainability important?

Source: https://www.pullrequest.com/blog/cost-of-bad-code/

SIG has collected empirical evidence that issue resolution and enhancements are twice as fast in systems with above-average maintainability than in systems with below-average maintainability. A factor of two is a significant quantity in the practice of enterprise systems. The time it takes to resolve issues and make an enhancement is on the order of days or weeks. It is not the difference between fixing 5 bugs or 10 in an hour; it is the difference between being the first one to the market with a new product, or seeing your competitor months ahead of you. Source: https://www.oreilly.com/content/what-is-maintainability/

In companies with 100+ developers, or an active codebase of 500K+ lines of code, maintenance accounts for more than half of the overall development budget. Source: https://www.krugle.com/resources/downloads/Krugle_WP_Hidden_Costs_of_Code_Maintenance.pdf

Essentially, if you write good, high quality, maintainable code from the start, you will have an easier job in the future for yourself when you need to make changes, and whoever is benefiting from this code whether it be yourself or another will have to spend less money or time on this in the future. Especially if someone else is introduced to the codebase.

Getting Started

Now, you can go to https://www.codeclimate.com/ and sign up via GitHub, this is useful because you can automatically link your repository to Code Climate.

Once you’re at the dashboard, you can add a repository via:

Add public repository button.

Then make sure you are sync’d with your github repositories, you should see something like this:

Front page of the code climate sync’d repository section.

Now, click “Add Repo”

Add repo button.

You’ll now see something like this:

Example of what the overview of a repo looks like on code climate.

Congrats! You have now added code quality analytics to your repository.

Let’s do a quick breakdown on what it all means.

What is a maintainability score?

“Maintainability score is a computed technical debt ratio, which is the total estimated remediation time divided by a very high level total estimated implementation time, based on repository size.” Source: https://docs.codeclimate.com/docs/maintainability-calculation#:~:text=To%20make%20the%20repository%2Dlevel,technical%20debt%20ratios%20are%20better

Test coverage is the percent of the code that has tests written for that code. As an analogy, if I had written 3 functions with 5 lines of code each, and I had two unit tests that fully covered two of the 3 functions, we would have 10 lines out of 15 covered, giving us 66.67% test coverage. Test coverage is not a perfect metric but it’s still useful, especially when creating devops pipelines. Check out my other articles for how to create a build pipeline and how to integrate test coverage.

Duplication is a subset of what code smells are. Code smells are issues with your code that can affect long term maintainability and code quality. Examples are functions that have too many lines of code that can or should be made into multiple smaller functions, or as mentioned above code that is duplicated when it could be made into a function to be reused. Check out this article for more examples https://refactoring.guru/refactoring/smells.

Here are a few examples of code smells:

Issues interface on Code Climate.

Code Climate provides an interface to see all your tech debt as well as estimated times to repair and an ability to filter based on severity. When you click on an issue, you are taken to the actual lines of code and the file where the issue was detected.

Large cognitive complexity function with 10 arguments.

The function has a very high “cognitive complexity” as well as 10 arguments. This is an example of tech debt, because imagine in 10 years if someone has to maintain it, it would be difficult for them to pick up what the code is doing.

Example of deeply nested control flow statements.

We want to avoid deeply nested control flow statements because they are difficult to read and have complex logic.

If you have a lot of code smells, duplication, low test coverage, you will have a low maintainability score.

And that’s basically it! As you update your code, this web page will continue to update. You can integrate this as you see fit to your repo.

PS. You can add a nice little button/badge to your repo now too. Simply go to code climate, go to repo settings, then to the bottom under Extras click badges. There will be one for test coverage and one for maintainability, you can put these in your repository README.md if you wish.

Picture of retrieving the badge from code climate repo settings.