April 26, 2017

...Learn TDD with Codemanship

20 Dev Metrics - 9. Readability

The 9th metric in my Twitter series 20 Dev Metrics is as important as it is contentious. Readability of code is a key factor in how easy it will be to change. Changing code we don't understand is like tinkering with car engines when we don't how they work. You're very likely to end up with something broken.

But, although there's pretty much universal acknowledgement of how critical readability is, opinions vary widely on what makes code readable and how we can assess its comprehensibility. Students may be told by their programming lecturers to write lots of helpful comments - the more comments, the easier the code is to understand.

Practitioners, on the other hand, may view over-reliance on comments as a sign that the code is not as self-explanatory as it could be, and seek to refactor the code to eliminate the need for them.

And how can we know if code is more or less readable?

By far the best indicator of how easy to understand code is is to see if other programmers can understand it. Well, obviously. My favoured method is the "code pop quiz"; before code can be committed, other developers have to answer some basic questions about the code to show they understand what it does and how it works. As with usability testing, when they can't answer a question, that indicates a failing in the code's ability to explain itself.

This is manual testing, though. And manual testing doesn't scale well. (Although many would argue that, as with inspections, making time for it would pay dividends later.)

Are there any automated - or automatable - ways we could at least use to target code that's more likely to be difficult to understand? Yes. and here are a few suggestions:

1. Complexity - more complex code tends to be harder to understand (tools available)

2. Flesch-Kincaid Reading Ease - is a metric often applied to teaching materials (tools available)

3. Keyword Density - is another metric applied to all kinds of texts (tools available)

4. Requirements-Code Keyword Overlap - can be calculated to show how closely the language of your code follows the language of the requirements specs (build your own tool)

5. Density of Comments - because, despite what your lecturer may have told you, comments really are an indication of unreadable code, and have their own maintenance overhead. (tools available)

6. Formatting - yes, really. The way we format code can have a pronounced effect on its readability. Don't believe me? Remove all the whitespace from some Java code and then show it to a colleague. (Automatable)

7. Conformance to Naming Conventions - can help, too (except when a dysfunctional conventions forces us to mangle names) (tools available)

You'll need a way to parse names in code so that, say, "checkAvailability" becomes "check availability", and so on.

Code that's more complex, has a low reading ease score, high keyword density and a poor alignment with the language of the problem domain may warrant more of your attention.

Posted 3 years, 4 months ago on April 26, 2017