Improve the Quality of Your Code with Better Code Hub

Better Code Hub guides you in writing Better Code. – BCH Homepage

So you pushed your code to GitHub and deployed v1, congrats! But how maintainable is your code really? Do you have tests? Is your code modular? Are your methods short and concise? What if you could hit a button and a tool conveniently checks this for you? Free and integrated with GitHub? Enter Better Code Hub from Software Improvement Group …

What is Better Code Hub?

You can read a nice introduction about the tool on their blog:

• Higher Grades for Better Code which defines the tool as:

  This newly-built software platform enables users to check the compliancy of software systems with the 10 guidelines for Maintainability introduced in the Building Maintainable Software book.

• And: Better Code Hub – An ambitious yet achievable Definition of Done for Code Quality. This is a nice read to learn about the motivation behind the platform:

  • First of all as Marc Andreessen famously said: Software is eating the world: every industry gets disrupted by software hence each company will become a software company.
  • Secondly GitHub has become the biggest collaborative developer platform with over 10 million repositories!

  This triggered us to create the Better Code Hub, an online service that puts 15 years of code quality knowledge at the disposal of all GitHub developers.

It supports 16 programming languages, can run upon each Push or PR (master and branches), and shows refactoring candidates with their impact. Last but not least: Better Code Hub provides software teams a Definition of Done, in their words:

If Better Code Hub compliance is achieved, you know you’re performing like the top teams in the industry. This is because the compliance thresholds are derived from a large industry and open-source benchmark that is calibrated yearly in our software laboratory to capture the state-of-the art in software engineering.

BCH has a nice design and a “zero set-up time”: just login with your GitHub account and it shows your public repos you can analyze:

At this point you can run the Analyze (play) button and SIG’s tool checks the quality of you code.

What does it check?

BCH will check your code against their 10 guidelines for maintainable software:

1. Write Short Units of Code – Short units are easier to understand.
2. Write Simple Units of Code – Simple units are easier to test.
3. Write Code Once – Duplicated code means duplicated bugs and duplicating changes.
4. Keep Unit Interfaces Small – Units with small interfaces are easier to reuse.
5. Separate Concerns in Modules – Modules with a single responsibility are easier to change.
6. Couple Architecture Components Loosely – Independent components can be maintained in isolation.
7. Keep Architecture Components Balanced – A balanced architecture makes it easier to find your way.
8. Keep Your Codebase Small – A small codebase requires less effort to maintain.
9. Automate Tests – Automated tests are repeatable, and help to prevent bugs.
10. Write Clean Code – “Leave the campground cleaner than you found it.”

These guidelines are based on an impressive body of experience:

Compliance to guidelines is derived from the Software Improvement Group’s industry benchmark which consists of over 8 billion lines of code in more than 180 different technologies. SIG analyzes around 15 million lines of code every week. – Better Code Hub Homepage

For more info I highly recommend their book. They have a certification program which I described here and I made this summary of the guidelines when I was studying for the exam.

Although we are a Python blog we wanted to discuss the tool here, because as Eric Elliott’s tweeted:

Frameworks and APIs change fast. Software design principles are evergreen. Learn principles that translate across language barriers.

Luckily Python (and its community) endorses a lot of good practices (import this folks!)

And we used it for a recent Code Challenge …

A practical example

I used the tool recently for our Code Challenge 30 – The Art of Refactoring: Improve Your Code:

At first I wanted to work on an old un-Pythonic script. Problem was: it would have been easy and some scripts are better dead and buried. So I thought:

Let’s do something real, something that we use and has to be mainained!

Hence I decided to use this challenge to refactor our Karmabot.

Heck, why not make it more robust now?! (Zen of Python: Now is better than never.)

It scored a meager 6 on Better Code Hub, hence it could use some work …

The refactoring process

1. First I added unittests to have a regression suite.

   Dealing with an external API (Slack) made this a challenge on its own, but luckily this awesome RealPython article made it relatively easy.

2. Then I clicked BCH’s Analysis button on the repo. Its guidance and rich UI made it a joyful experience. I refactored more than I anticipated making the solution leaner and better maintainable (although not as granular commit history here for reference).

Examples of what BCH caught:

No tests!

OK that’s better, now we can actually start refactoring!

Tackling complexity:

Various issues here: number of branch points, 3 method (interface) params and violation of the Single responsibility principle. This example led to various refactorings even changing part of the karma module into a class.

Although not the final result, BCH made the refactoring progress very visual:

When I thought I was done BCH still pointed out I should “Couple Architecture Components Loosely”. It turned out main.py and karma.py were too entangled:

Moving _process_karma_changes from main.py to karma.py solved this.

It felt like everything fell into place, probably due to earlier refactorings. This was one of those aha moments.

And the final result:

Lastly SIG made a nice badge you can add to your Project’s README:

Try it out!

Some code to refactor? Or starting a brand new project? Try this tool out and let us know what you think in the comments below.

You can follow / reach out to them on Twitter.

For above mentioned and other interesting articles check out their Medium page.

And above all keep learning and growing. Writing quality code is hard and takes a lot of practice (I am no expert, I am the student).

A final word of thanks. I feel fortunate to be able to learn from SIG’s body of experience and knowledge and their new platform that brings their SW quality guidelines to the greater community. Great job SIG!

---

Keep Calm and Code in Python!

— Bob