Code maintainability is a fundamental part of good software development. It is important because as code becomes less maintainable the cost to maintain the code increases. There are more bugs to fix and it’s more difficult to add new features. Also new developers find less maintainable code more difficult to learn and it takes them longer to contribute to a project, driving up costs further.
If we were to plot cost against code maintainability it would look something like this:
As maintainability increases costs fall. Maintenance costs never fall to zero but they do fall dramatically as a codebase improves.
One problem with code maintainability though is it’s difficult to quantify. What does maintainable code mean or look like? There are tools like Code Climate which attempt to define it, but they don’t offer a lot of detail on what it means. Also it’s not always possible for a development team to use a cloud based tool like Code Climate.
To help I have created a quick ten point Code Maintainability Test. It is similar in intent to the Joel Test, it is a bunch of simple, binary questions. For a positive answer you score a point, and the closer your score is to ten the more maintainable your code is.
Of course this test is not meant to be comprehensive. It is only meant to provide a rough guide to how maintainable code is. Like sticking a licked finger in the air to test the direction of the wind. It does not capture all the nuance of code maintainability.
The test is broken down into three parts:
- Usability: how easy is your code to learn and contribute to?
- Bug Density: how many bugs do you have to fix?
- Code Complexity: how easy is your code to understand and extend?
The Test
Usability
Usable code is easy to learn and fast to contribute to. Well formatted code with good documentation is usable code.
- Do you have a well written README which explains installation, setup and usage? (+1 Point)
- Do you have clear code comments which explain the existence and intent of the code? (+1 Point)
- Do you run code lint tools? (+1 Point)
Bug Density
Strong types, static analysers and code tests will all reduce bug density. The lower your bug density the fewer bugs you’ll have to fix in production.
- Do you have a code coverage score greater than 60%? (+1 Point)
- Do you have a code coverage score greater than 90%? (+1 Point)
- Do you run mutation test or fault injection tools? (+1 Point)
- Do you use a strongly typed language or run a static analyser? (+1 Point)
Code Complexity
Code with low complexity is easier to read and understand, easier to test, easier to debug, and easier to extend.
- Do you run mess detection tools? (+1 Point)
- Do you have an average code complexity below 10? (+1 Point)
- Do you have an average code complexity below 5? (+1 Point)
Scores
0 - 3 Points: Your codebase is difficult to maintain. It will have a high bug density; It will be difficult to add new features; New developers will struggle to learn the codebase and contribute; Costs will be high; A long and difficult rebuild is likely.
4 - 7 Points: Your codebase will have maintenance issues. It will have a moderate to high bug density; Some features will be difficult to add; New developers will struggle with aspects of your codebase; Costs will be moderate to high. Improvements can be made.
8 - 10 Points: Your codebase is easy to maintain. It will have a low bug density; You can easily add new features; New developers will learn the codebase quickly; Costs will be minimised. Keep up the good work.
Tools
Below is a list of tools which can help with testing and code analysis which will improve code maintainability. It is not a comprehensive list, there are loads more tools out there across many languages.
Testing Tools
- Jest (JavaScript)
- Mocha (JavaScript)
- Chai (JavaScript)
- PHP Unit (PHP)
- Codeception (PHP)
- Mockery (PHP)
- Tarpaulin (Rust)
Mutation Test Tools
Code Analysis / Quality Tools
- ESLint (JavaScript)
- PHP MD (PHP)
- Code Sniffer (PHP)
- PHP Loc (PHP)
- Radon (Python)
- Pylint (Python)
- Rust FMT (Rust)
- Clippy (Rust)
Static Analysis Tools
I do hope this is useful, and if you have any questions, thoughts or criticisms drop me a message on Twitter @RobDWaller.