Toughts about… What is Code Quality

What is Code Quality

Code quality is not easy to define. To me it is a certain level of uniformity, a minimum of documentation, a low complexity per method and class, a clear separation of concerns… To other developers other things may be more important. The definition of code quality that should matter is the one all team members can agree upon.

One of the most universal but rather abstract definitions I ever read is LTFCE found in this Stackoverflow answer:

  1. Legible - The code (the code itself, not comments) should clearly state the intent. If the reader can't make sense of the code, than all other efforts are doomed to frustration if not outright failure.
  2. Testable - The code should be organized in a way that facilitates unit testing. That supports all subsequent efforts (refactoring for modification, correction of defects, revision due to changed specs, etc.)
  3. Flexible - Dependencies, both on other code in the code base and arbitrary implementation choices, should be minimized. Hard-coded assumptions about data size, concrete classes or data structures, etc. make the code more brittle, and therefore harder to reuse or adapt.
  4. Compliant - The code should comply with its requirements, functional and otherwise. (I don't state this as "correct" because the discussion about whether the requirements themselves were the "right" requirements is about the process or the environment, not about the code.)
  5. Economical - The code should make reasonable use of system resources: memory, CPU, etc. (I don't state this as "efficient" because that word is too often misused, by limiting it to a single aspect, such as speed. Economy is simply about return on investment, and requires thought about all the resources being invested and all the measures of return.)

While I think these are pretty brilliant guide lines, they are quite abstract. All professional software developers should agree at least with most of these goals. But there are rather different measures to achieve them. So we should take some time to get that common understanding and write it down as a Definition of Code Quality (DoCQ) and make it part of our Definition of Done (DoD).

How to Write a Definition of Code Quality (DoCQ)

A DoCQ (just like the DoD) after all is a collection of requirements we set for ourselves, I think we should write our Definition of Code Quality in the fashion that not only defines what is wanted, but also who wants it and for what reason. That's right, I suggest to write down a list of user stories.

User Stories for the DoCQ makes sure we reflect the purpose of out requirements. If you ever worked with (well written) user stories you know this effect: it is far more easy to work constantly towards a goal – or in this case to follow a rule – if you know its purpose and make sure it is met. It is possible to remove elements from the DoCQ if you know who wanted it and can argue that its purpose is met in other ways. It is also possible for the Product Owners to understand why you care about these rules. They might even defend the rules and add their name/role to the who part of some.

Here is an example for a DoCQ story:

As a developer using Eclipse,
I want all parameters documented in JavaDoc,
so I get the documentation when I hit Ctrl+Space while using the method.

All your team members switched to Idea? Maybe this rule is no longer needed then since it was important for Eclipse developers. Is there more to this rule? No? Delete it from your DoCQ right away. There's more to this? Change the who and the why and keep it.

How to Measure Code Quality

To be honest, there is no true way of measuring code quality as defined by the LTFCE guide lines. These require a human brain to be checked. However there's a whole lot of tools to ensure certain (DoCQ) rules are properly applied. I personally like setting up a Sonar and let my build tool feed it with information from FindBugs and Checkstyle. Then I simply add some Sonar rules to represent the rules defined in my DoCQ. If you don't know how to do this, this screencast is a very good place to start.

Also you will need a good base set of FindBugs and Checkstyle rule sets. I suggest to use the standard set and deactivate some rules you don't want to have.

Avoid Broken Windows

If you want to use a rule but have one certain piece of code that cannot be changed to apply to it, you should not tolerate the violation but mark it as an explicit exception to the rule. There is a section about avoiding false positives in the http://docs.codehaus.org/display/SONAR/Frequently+Asked+Questions#FrequentlyAskedQuestions-NOSONAR. I personally like to use NOSONAR comments. For example: // NOSONAR because we need a main method in this class. But the other might suite your needs even better.

Conclusion

Getting a DoCQ in my opinion is the only way to turn good intentions into real tasks to work on. A monitoring system like Sonar can help even more and provide a way out of messy legacy code.