# a blog about things that I've been thinking hard about

# A New Job: Source Code Quality Controller

21 August, 2008
Source code quality is a specific aspect of software quality which needs to be managed by a specialist source code quality controller.
by Philip Dorrell

## The Importance of Source Code Quality

In my previous posting on the Economics of Testing Ugly Code I showed that there is no "later" when it comes to fixing "ugly" source code.

Which means, that if code quality is important, then all code problems have to be fixed sooner rather than later.

But, who should be responsible for maintaining "source code quality"?

## If you want a job done ...

If you want a job done, there has to be someone whose job it is to do the job.

There are alternatives, but they are not very good alternatives.

### Alternative 1: Hope It Gets Done Because It Should Be Done

Making code be not "ugly" seems like something that developers should be responsible for, since they are the ones writing the code.

The problem is, the job of developers is mainly to write code to implement features which can be tested and then checked off as "done". Fixing "aesthetic" problems in the code goes into the "do it later" category, i.e. maybe not at all.

### Alternative 2: Do It By Committee

This is the infamous code-review meeting. All the developers get together and review some part of the code. Like all committees, code review committees get weighed down by group-think, i.e. "this is the way we all do it, so it must be a good way to do it". Typically minor obvious problems get noted (and fixed), but the really big things, like ugly code caused by architectural decisions made at some earlier time, are classified as out-of-scope, as they are beyond the control of the individual developer who wrote the code, and since code review is a kind of criticism, it seems unfair to criticise the developer for something that's not their fault..

### Alternative 3: A Set of Rules

If coding standards are specified by a well-specified and precise set of rules, then everyone knows in advance what is "correct" and "not correct", and there is nothing to argue about. If the rules are sufficiently precise, you don't even need code review – you just have a script which runs on new code and complains about anything that breaks the rules.

## Code Quality is a Specific and Somewhat Subjective Aspect of Quality for a Software Project

The overall quality of a developed software can be divided into various aspects. For example:

- Correctness of operation
- Required functionality (or, depending on the nature of the project, useful functionality)
- Ease of use
- Security against relevant threats

The quality of source code is yet another aspect. "Source code quality" can be defined as all those aspects of the source code which do not necessarily have any impact on the run-time behaviour of the application (which is what the first four aspects all relate to), but which are likely to affect the ability of developers to comprehend and change the software in the future (whether it be to fix existing problems or satisfy changing requirements).

For any type of project, whether it be software or something else, as the project gets larger, and requires a greater number of workers to get it finished in a reasonable amount of time, it becomes more worthwhile to allocate different aspects of the work to specialists in those aspects.

So correctness of operation can be tested by testers, functionality is prescribed by business analysts, ease of use is managed by interaction designers and security is tested by specialised application security testers.

It follows that source code quality should also be managed by a specialist, i.e. by a specialized source code quality controller.

### Like Editing a Book

Source code quality is mostly about organisation and readability. In treating source code as something to be read, source code quality control is similar to book editing. In the case of a book, the content is written by an author. An author is expected to write readable well-organised content on whatever the book is supposed to be about. Nevertheless, professional book publishers employ specialised book editors whose job it is to make sure that each book is as organised and readable as it possibly can be.

The book editor's job is to read the book and note any problems of organisation, flow or comprehension, so that the author can fix those problems.

Interactions between authors and editors can be tense, when authors object to undesirable changes to "their" content. But no major publisher would publish a book without having a book editor work on it first.

A book publisher would certainly not allow book editing to be done by any of the three alternatives listed above:

1. Assume the author will avoid or fix all problems
2. Allow a committee of authors to edit each other's books
3. Run the book through a software program that automatically identifies and fixes all problems

## Who Actually Cares About Source Code Quality?

Because the benefits of source code quality are more long-term than short-term, it is the owner of the software being developed who should care most about it.

For mass-market or open source software, the owner is usually the same as the individual or organisation which is developing the software.

An individual developer is their own source code quality manager, and that's the way it always has been.

For a larger organisation, if source code quality matters, then the organisation needs to appoint someone specifically to manage that aspect of quality. (I'll get to the details of what this person actually does soon.) This person is assigned specific responsibility for source code quality, and will be involved with all decisions which affect source code quality. Of course everything in any kind of project involves give and take between different people responsible for different aspects of the project's success, and it is part of the source code quality controller's job to be part of that give and take.

When software is developed under contract, then typically the owner of the software is not the developer, and source code quality becomes a hidden moral hazard. Given the tendency to judge the quality of software entirely by its runtime behaviour, source code quality by default becomes a low priority item.

If you are a customer of a software developer, and you can understand why source code quality matters, then it is up to you to task someone acting in your interests to monitor the quality of the source code being written for you, and to raise specific quality issues and have them fixed.

Of course this can be problematic for fixed-price contracts. Given the very subjective nature of source code quality, it is difficult to write down a legally binding description of how good the quality of your source code should be. So if source code quality matters to you, then you will probably have to opt for charge-by-the-hour development.

### Outsourcing

Outsourcing is a special case of getting software developed under contract, but with additional difficulties of communicating with people in another country who probably don't speak your own language as a first language.

Applying the concept of source quality controller to outsourcing, it follows that you should:

- Pay hourly rates
- Employ someone directly within your own organisation to monitor and actively maintain the quality of the source code

In other words, don't just send out the requirements and wait three months for the code to get written.

## The Source Code Quality Controller

Who is the source code quality controller?

He or she is someone who has been assigned specific responsibility for source code quality.

Someone who is good at reading source code, but not so good that they are happy to read code that is messy and ugly.

### Treating Ugly Code as a Bug

One of the important tools of modern software development is the bug-tracker, or, if we want to be more general, the issue-tracker.

Given the use of such a tool, source code quality issues can be raised as issues just like any other issue, and assigned back and forth between the quality controller and developers (and anyone else who needs to get involved).

Although I said above that code quality cannot be reduced to a set of rules, there are some aspects of code quality that often can be, for example consistent code formatting conventions, and scripts can be written (for example by the code quality controller) to detect and/or fix relevant problems.

And although it is primarily the quality controller's job to manage source code quality, other developers should be able to raise their own issues, if they see problems, which would be assigned in the first instance to the code quality controller.

### Types of Issues

- Bad variable/class/method names
- Repetition
- Too much code in one place
- Too convoluted
- Undocumented
- Bad formatting

### Hard Issues

Not every code quality issue will have an easy fix. For example:

> Too many methods of form setX and getX with repeated boilerplate code.

The only "fix" for a problem like that is not to use Java, and depending on the circumstances of the project, it might go into the "noted-but-too-hard-to-fix" category.

Nevertheless, this type of example suggests that the job of code quality controller is not just to critique the coding efforts of individual developers, but that they will also play a role in designing overall software architecture. Because, as I have seen myself many times, choices of framework and platform can be a major cause of ugly code, and if code quality matters, then this needs to be taken into account when making these choices.

## How Will Developers Feel?

It is possible that developers may feel oppressed by the appearance of a source code quality controller.

However, there are various reasons not to be too concerned:

- Even without explicit code quality control, conflict still occurs, because by default developers have to tolerate the existing state of the code-base, which is a product of a mixture of other developers' ideas about how to write code and of an accumulation of random historical circumstance. A clear individual vision of how code should be written may be easier for the developer to work against than a de facto set of "rules" and arbitrary "best practices" accumulated by a development organisation.
- Developers can pick and choose which code quality controllers they want to work with. The quality controller can say "here's what the code looks like when I'm in charge of code quality", and the developer can show what sort of code they like to develop, or what they have developed. If there's a reasonable match, then the developer and quality controller can look forward to a positive relationship.
- Attempting to maintain code of poor quality is itself a stressful experience. An explicit commitment to consistency and readability should reduce this stress in the long term. It also encourages developers to raise code quality issues. (Actually, developers may be quite happy to raise these issues already, but often there is no official place to raise them. After all, code quality issues are not "bugs".)
- Various forms of specialised quality control are the norm in many industries. For example, actors don't just act in front of the camera – there is a director who directly manages the film-making process, and who is usually working against a personal vision of how the product should turn out. Authors have book editors (as already mentioned). And musicians don't just record in the studio; they have producers.

## Predictions of the Future

In the present, some of us know, at least some of the time, that source code quality is something that matters.

But so far we have not really committed ourselves to source code quality, because we have not defined it as a responsibility to be assigned to someone who is to be paid real money to have that responsibility and to make decisions about how source code quality is to be maintained and improved over the course of a software development project.

But, sometime in the future, I think we will look back, and we will be surprised that we ever thought that source code quality was something that would just "manage itself".

Vote for or comment on this article on Reddit or Hacker News ...