Why Developers Should Not Code

The ultimate problem with program code seems to be that no human really understands it. Sure, we can look at a short piece of code and be relatively clear on what it does, but can we still do the same thing with programs that span tens or even hundreds of thousands of lines?

I remember, years ago, a senior developer saying to me:

"The thing I find so intriguing about C is that if you ask three developers what a short program does, you will get three different explanations".

In the famous 1999 Refactoring book, Martin Fowler, Kent Beck et. al wrote:

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."

Well, sometimes I get a strong feeling that there is a shortage of good programmers, because I often find myself looking at legacy code, being unable to tell what it does, at least with reasonable certainty.

Beyond Doubt

Personally, I already consider code to be problematic when there is a reasonable amount of doubt as to what it does (and why it exists). To me, uncertainty and discussions are a sure sign of bad code. Call me picky, but years of experience have taught me that this level of strictness makes sense.

One of the most important lessons good developers need to learn is: recognizing that existing code is hard to understand does not make you a poor developer. Quite on the contrary.

The word code, in fact, has multiple meanings. As far as I could find out, it originates from the Latin "codex" which basically means a piece of wood to write on. Later, the meaning turned into "system of law" in Old French. Well, I think we all would agree that a "code of law" definitely is already something nobody really understands.

Another meaning of code is cypher, a "message represented by rules intended to conceal its meaning". Recently, the word code also started to denote "instructions for a computer".

But code is the wrong term. A computer program is not meant to be cryptic, hard to read, concealed, or even mystic. We write code not for computers, but for humans to understand. Try to understand code that you have written three years ago if you still do not agree with me.

Before everybody turned agile (or at least claimed to do so), people wrote big requirements specifications, and then tried to turn them into working software. One of the big unsolved problems of this approach always was that nobody was really able to find out whether the software would fulfil all requirements (or any of them, for that matter).

Executable Specification

Some people, including me, argue that automated tests should be an executable specification. And since agile methodologies have taught us that it is rather pointless to write those big specifications up front, why not write up the specification in small increments?

One may do so by writing a failing automated test first, and then working their way towards making it pass. Another frequently used approach, admittedly less sophisticated, is to write a few lines of program code, and then hitting F5 in the browser to get that program executed.

Without an automated test, though, the specification is never written down, but only temporarily exists in the mind of one developer. Over time, this knowledge is lost, and a few weeks later some degree of uncertainty about what the program does – or what it should do – starts to spread. Over time, it will spread like a virus, and infect the whole organization.

Writing down a computer program in a human-readable fashion, and using automated tests as an executable specification of what the program does (or does not do) frees you from prosing extensive specification documents. But saving on paper documentation while writing unreadable code will have you end up with another legacy system that nobody understands.

I will follow up on these thoughts with my presentation Domain-Specific Languages in PHP later this year. In the mean time, can we please abandon the term code for computer programs?

About the author

Stefan Priebsch
Stefan Priebsch
Twitter LinkedIn Xing
Share this article
Testing Keeps Me From Getting Things Done Don't call instance methods statically