Constraints that drive creativity

A different code quality philosophy

Should you measure and control code quality? According to a poll conducted by O’Reilly Media and my colleagues at the Software Improvement Group, virtually all developers say YES! Here’s a number of compelling reasons:

• Happiness: Better code and happy developers go together. It’s more fun to work on code that is good. In fact, bad code quality and coding practice were identified as the number 3 cause of developer _un_happiness. In case developer happiness is not sufficient as an intrinsic reason, think of the increased productivity and retention that will follow.

• Speed : Good code is easier to understand, easier to adapt, easier to test, and easier to reuse. By definition. Quickly write up some bad code now, and fixing bugs or adding features will take up more time in future. Or in other words: “Current development speed is a function of past development quality”.

Brian McCallister

@brianm

Current development speed is a function of past development quality.

18:31 PM - 10 Aug 2016

858 685

• Agility : Being agile in software development is not just about processes and best practices, but also about making frequent changes to your code. To accommodate and ship the next feature. Or to respond to changing requirements. Or because you learned how to express your intentions better. High-quality code allows you to make these changes frequently and effortlessly.
• User satisfaction : When developers are happy, fast, and agile, they can build the best possible products. With the functionality, performance, reliability, and other quality characteristics that you users expect and appreciate. So ultimately, better code means better business.

Most teams do not properly control code quality

So code quality brings compelling benefits. But now the shocker. Not all professional software development teams actually measure and control code quality in a professional manner. In fact, when assessing software development practices across many organisations over the past several years, we found that about 83% of the teams do not control code quality at all or only do so partially.

Why not?

What are the main reasons cited for not applying code quality control? What is wrong with the tools that are available for this?

1. False positives and lack of actionable recommendations: Unfortunately, many code quality tools flood their users with a large number of violation alerts of which only a small percentage is valid and actionable . As a result, the output of these tools is often ignored.
2. Too costly and too difficult to configure : To improve the validity and actionability of their output, some tools offer extensive configuration options. They also come with the possibility to extend the standard behaviour by supplying rules sets that are specific for your team or your product. Such configuration and customisation may seem like a cool and advanced feature. In fact, they may be advertised as unique selling points, justifying higher license fees. But in fact, it means you need to invest valuable time of senior developers in learning and maintaining these tools that were not cheap to begin with.
3. No clear standard, across teams and technologies : Another disadvantage of customisation is that it undermines standardisation. When each team or developer uses his own set of quality rules, or even different sets of rules for different programming languages, then how can we as developers aspire to the same level of quality? Software development is a socio-technical discipline, just like driving. In traffic and in development, we can prevent accidents and travel fast, only when we all stick to the same rules of engagement.

A different code quality philosophy

At the Software Improvement Group, we set out to resolve this apparent conflict between the (economic) necessity of controlling code quality and the poor adoption of code quality tooling. To do so, we needed a different perspective on code quality.

Our key insight was that we need to raise the level of abstraction from individual code quality violations, that are observed in particular code locations, to quality profiles that characterise an entire code base or a significant portion thereof.

The simplest example of such a quality profile is “the percentage of code lines in methods longer than 15 lines of code”. This quality profile can characterise the readability of a single class, a package, or an entire code base. A lower percentage means higher readability. While grounded in quality measurements in specific code locations (methods in this case), the profile does not pinpoint any specific location as a “violation”. Instead, we can formulate quality norms at a higher level of abstraction, for instance by demanding that said percentage does not exceed e.g.  20%.

Quality profiles allow to set crisp, actionable thresholds (e.g. 15) for measurements that are highly relevant to code quality (e.g. method length). But they also come with an intrinsic concept of tolerance where a fair amount of code is allowed to surpass the threshold (e.g. 20%), but the developers retain freedom within those limits to decide which violators to accept and which to refactor.

Ten Guidelines for Future-Proof Code

Based on this philosophy, we formulated Ten Guidelines for Future-Proof Code.

Note that these are guidelines , not rules. A rule is binary, drawing a line between right and wrong. Compliance or violation. But a guideline merely provides direction. A guideline allows choice within a clear boundary. In software development, as in art, well chosen constraints do not limit, but enhance creativity.

“Creativity is driven by constraints” — Dave Grey

We calibrated both thresholds and tolerances in these guidelines against code analysis results from hundreds of software systems. Together the 10 guidelines provide a crisp definition of done for code quality. A definition of done that is ambitious, but not overly restrictive due to intrinsic tolerance. And we built the Better Code Hub to check those guidelines for you on your code base.

Better Code Hub

The purpose of Better Code Hub is to show that a different approach to code quality control is possible. An approach that is less cumbersome, less restrictive, and more fun. Here is what it does for you:

1. Provide a crisp definition of done , that is independent of technology, team, or product. A single standard for code quality.
2. Easy adoption and immediate feedback. Through the GitHub Marketplace (free for open source, start-ups, and educational use) you can run Better Code Hub on your code within minutes. And by flipping one toggle, you activate feedback on each push and pull request.
3. Refactoring assistance : Better Code Hub tells you not only which guidelines your code does and does not comply with. It also provides you with refactoring candidates. And when you make a selection of candidate to refactor, you get a real-time prediction of how your guidelines compliance will be impacted.

So, if your team is not measuring and controlling code quality yet, this is the time to start. Give Better Code Hub a try. It will be fun!

Joost Visser is CTO at the Software Improvement Group, Professor of Large-scale Software Systems at Radboud University, and author of O’Reilly books “Building Maintainable Software” and “Building Software Teams”.

• Building Maintainable Software, Java Edition
• Building Maintainable Software, C# Edition
• Building Software Teams
• Better Code Hub - GitHub Marketplace