Image credit: welcome_to_nunavik on Flickr
To help visualise and manage the quality of our codebase at work we've started to use SonarQube - an open source quality management tool.
The codebase is a very old one that how can I put this nicely has been built with other goals in mind. We now find ourselves trying to understand why we have this code, what the code is doing and trying to retrofit standards.
It's a Python codebase so we have PEP-8 for coding standards and can use tools such as Radon to understand the complexity of code but SonarQube gives us all that and more with very little configuration.
It's important to manage the quality of you code the same it's important to manage the quality of your product (especially if your code is your product like in open source projects).
With a product you can set a quality gate of criteria the product must meet this normally involves tests for material defects, tests at different assembly stages and tests once the whole product is assembled so you can ensure it's safe to ship.
In the factory that makes a product the workstations and factory floor will be held to a similar quality gates which are in place to ensure the proper running of the factory.
In Lean & Just In Time Manufacturing the 5S help with this, these are:
- Sort - Make sure we only have the things we need to do the job, no clutter
- Set - Make sure the tools we use are in order based on the workflow
- Shine - Make sure the work area is clean and equipment is maintained
- Standardise - Make sure standards are set and maintained
- Sustain - Make sure the discipline to follow the process is maintained
While with a software product you do these tests as unit, integration and system testing we don't generally look to organise our workstation similar to how a factory might.
In this analogy the workstation is the codebase and the tools are the modules, classes, methods and lines of code we use within the codebase to make the final software product.
So where how does a quality management tool help us? It helps us to
- Sort - We can ensure we're not cluttering files with checks of complexity and lines of code in our classes
- Set - We can ensure the codebase follows a logical structure
- Shine - We can set linters to ensure code is commented and tools to ensure complexity is low
- Standardise - We can set standards for our code, SonarQube allows us to set standards based on Regex matches and using XPath against an XML representation of the code's Abstract Syntax Tree
- Sustain - We can ensure all code conforms to a set of defined standards and highlight any non-conforming code
Using SonarQube with Git Flow
At work we use Git Flow. I like Git Flow as it allows for code to be worked on separately of the rest of code base (although it's important to merge develop into the feature branch often) and then merge the changes in once the code has passed the quality checks we want.
Luckily SonarQube supports branching using the
sonar.branch property in the
sonar-project.properties file it uses to define how the project is setup.
This means the quality of a feature branch can be maintained without affecting
the main branch.
The issue assignment and action plans really fall into their own if you're using feature branches to drive the improvement effort in a particular direction as you can track the progress being made with each commit.
Using SonarQube with Travis CI
We also use Travis CI. Travis CI is an amazing Continuous Integration engine which makes it easy to configure the CI environment and work really well with Github and the Git Flow branching strategy.
However, as the details of our SonarQube need to be protected it can be a bit daunting trying to get it to work with Travis. Luckily Travis offers secure environment variables which allows encrypted strings to be defined in the travis.yml that are decrypted at run time.
We use this method to define the following in
We then use ssh to bind the ports of the local SonarQube on Travis to our remote SonarQube.
One thing to note is that if you're using a matrix it's a good idea to set an
environment variable that controls when
sonar-runner is run. This is especially
important if you're running a subset of tests or using a subset of the codebase as
SonarQube will look at these matrix separately to build the full picture.
The most important part to note is that running
sonar-runner, especially on a
large codebase will take some time so it can add up to 10 minutes to the build
Quality Management tools such SonarQube really help you to keep on top of your codebase. If you're testing your code then you should really think about setting up an instance and using it to track your code's quality.
SonarQube offers a lot of options so it's important to know what quality metrics you want to use it for and as with most things work on that core set before branching out into other metrics.
In general having a code quality information radiator such as SonarQube will help the team understand the state of the codebase better than infrequent code reviews.