Article: Code quality - A Rambling

Published: Title: Code quality - A Rambling

Code quality is a rather subjective phrase to describe the kind of code a piece is. It tries to put it into a nice 'bin' of either good, bad or somewhere in between. But really, like any art form (which programming is definately among!), it is all for the viewer to decide. So here is my views on the subject.

First and foremost my views on code quality come down to one thing, it is a medium in which thoughts and concepts are transferred. It does not exist to drive a cpu or a compiler. It is there to transfer an idea or subject goals to others. Who reads it, a compiler, linter or another person is irrelevant to the code.

Now that we got out of the way my core belief, lets go on to how it reflects into more real world subjects.

General context

The first breakdown I have made here, is a list of things which are rather immediate in the problem-space for any code.

  1. Can it be understood by the compiler?
  2. Does it work?
  3. What is its purpose?
    • Can it do anything else?
    • Should it be doing something else?
  4. Will it fail in the future arbituarily? e.g. time (Y2k)
  5. Are there any known problems?

None of the things in the above list discusses styling or have you got X. Because for the most part these are secondary and can be improved later on in the development cycle.

The reason that list matters to both me and generally other people is it removes surprises. When there are surprises in codebases bad things happen. It can potentially cost millions of dollars and human lives. All around it can be a real pain and quite dangerous to everyone involved.

But most importantly that list isn't just about code quality, it is about the project quality. Although they may be one and the same depending on the codebase.

Code measure

Onwards and on to the code itself. Earlier in this article I choose to emphasize the phrase that code quality is quite a subjective thing and I do wish to reiterate that here. Some programmers will require a specific style, but in general any such discussions is never going to end in everybody being happy. So I think it would be best if this was to be ignored in any such discussion.

So for this, we look onto more solid metrics, specifically does it convey and perform as requried?

  1. Does it do its job?
  2. Can it be understood by a human?
  3. How much does the compiler complain about it?
  4. Will it pass a code style check (personal/pre-defined doesn't matter, just has to be consistent)?

The above list has quite a bit of overlap as the one provided in General Context and this is no coincidence. Because all of these things impact upon how a user or developer interacts with it and quite importantly, further development.

Of course this sections who goal is about the code itself, so lets go with a few more.

  1. Organized in a way that reflects the idea/concept.
  2. Seperate concepts, seperate areas (files/areas of a file).
  3. Grouping of resource usage
  4. Depth from purpose
  5. Naming

The order matters in this list. Keep ideas, concepts and algorithms close together (e.g. modules/packages) with hierachy that matches. Ensure a clear seperation of duties. Assert limited degrees of seperation between the purpose of that code and what code is in there (e.g. nested statement depths). Lastly name things which describes what it is doing/goal.

You may have already spotted an issue here, what about comments! Descriptions, documentation! Well, you are not wrong. I missed them on purpose. For one very important reason.

Code is documentation!

You cannot expect formal documentation to be accurate or up to date. Instead you must rely on the code if anything is not quite right. My experience for hesistance to this results from ecosystems that in general have poorly written code. With non-engineering values at the core of them or some kind of misguided belief.

While the above lists detail some things, I am sure loads have been missed out. Got any ideas for more things?