The Library vs Frameworks Debate is Over


Clarity in Software

by coatta 5/24/2009 9:21:00 AM

I've been wondering about what makes good code recently, or to phrase it another way, what are the basic principles that you can follow that will generally keep you pointed in the right direction. I've come up with two that really stand out for me: correctness and clarity. The former is obvious, but can be turned around into something more useful -- that is, you can't code something until you've defined what it means for it to be correct. So there is a need for well-specified requirements and even perhaps a motivation for techniques such a test-driven development (TDD). I can't say that I've gotten to the point of doign TDD myself, but I can't imagine working on a project without a solid set of unit tests and the continuous integration tools to ensure that they are run whenever the code changes.

Clarity, on the other hand, is not so easy to draw a box around. Like all issues of communication between human beings there is no scientifically proven right way. But that should not be an excuse to ignore the issue. In fact, as time goes on we're seeing that software is not really emphemeral -- that is, much software continues to be used and modified over long periods of time. Because of this clarity is increasingly important because it governs how difficult it is to maintain and modify a given piece of software (see

So how does one achieve clarity in software? As I mentioned above, this is really an issue of communication. In this case, does the source code effectively communicate its structure and purpose? I don't believe in the idea of self-documenting code. There are always design issues and requirements related information that needs to be communicated via prose -- although that can simply mean as comments within the code. However, the code itself can either contribute to one's understanding of the software or, in the worst case, it can detract.

I think that there are lessons to be gleaned from best practices in technical writing. For example, in writing that is expository in nature, the rule of thumb is that one should begin with an overview and then proceed to elucidate the points identified there. To me this is very much akin to the idea of starting at a high level of abstraction and then working down through successively more detailed layers. But what do I often see when I read code? Something that starts with private member declarations and helper routines and works its way up to the more abstract operations provided. This is completely backwards from the point of view of good communication. Now I realize that back in the bad old days, compilers couldn't handle forward declarations so this inversion was necessary, but there's really no excuse for it now.

Even worse than this, are source files in which there is no discernible organization at all. Public and private declarations are interspersed and there is no rhyme nor reason to the proximity of various elements of the code. My own theory is that this is often the result of development environments which provide sophisticated tools for navigating within source code. When you can immdiately get to a definition by choosing it from a drop-down, or can find the something with a mouse click or two, the actual location of those entities within the source code starts to become irrelevant. But to someone who is reading the code for the first time, the lack of structure is aking to reading an article in which the order of the sentences had been randomized.

Another style which I find takes away from clarity is statements that compose a large nubmer of actions together. This is great if you'd like to win the Marcel Proust Award for Turgid Code, but looking again to best practices in technical writing we find that the ideal is normally short concise sentences that convey essentially one idea. Brevity is not the utlimate goal because at some point increased brevity impedes communication.

There are many other aspects to writing code that is easy to understand. In fact, there is quite a history for literate programming that you can look into (see But the main point that I want to make is that programming is more than just creating functionality. Its also about communicating to others and that requires a different kind of thinking about the code that we write.    


<<  June 2020  >>

View posts in large calendar



© Copyright 2020

Sign in