Programmer Musings

The Most Important Result of Writing Code

It's not a big surprise that most programmers feel that the most important result of writing code is the code itself. Other people might argue that while the code is important, other things are more important:

• Results of the execution of the code
• Money made by selling the program
• Business value realized by running the code

With a little effort, you (the programmer) might be able to convince yourself that these items are as important as the code itself. After all, if it weren't for the value that the business gets from your code, they would not pay you to write it.

Putting aside the business considerations for this discussion, I would still say that there is a more important result to the developers than the code itself.

What does the code represent?

When we write code, we actually take our thoughts and understanding of a problem and put it in a form that can be executed. This isn't quite the same as assembling a machine or knitting a sweater. The code is a relatively direct representation of something that only existed as thoughts in your head right before you began to type.

The code represents your knowledge and understanding of the subject. The code is only a representation of the most important thing you gained from writing it. The important part is the increase in knowledge or understanding that you gained.

What's the difference?

The difference is subtle but important. Once I understand a solution to a problem well enough to code it, I could probably write that solution in different languages or forms fairly easily. I also have the ability to explain the solution better than I did before it was coded, because the act of coding forces me to get the details right and (usually) think through edge cases and boundary conditions.

I realized this was the case years ago when using one language to prototype a quick-and-dirty solution to a problem before doing the real implementation in a different language for production. It turned out that I could get the prototype working in the original language much faster than I could in the production language. This allowed me to really explore the idea in a limited time frame. But, when the prototype was finished, the knowledge went into building the production version. At that point, I could discard the prototype. It had served its purpose.

Why does it matter?

One problem that I've seen repeatedly with programmers is an inability to throw away code they have written. This sometime leads to years of patches and band-aids to a piece of code that should have been rewritten, or at least aggressively refactored. Maybe the original algorithm was way too slow. Instead of replacing the algorithm, the programmer adds a level of caching to speed things up. Then, come the tweaks and micro-optimizations. Eventually, it becomes one of those pieces of legacy code that no one wants to touch.

Everyone is willing to re-write someone else's code. But, we are usually more reluctant to throw out our own.

Another place where this problem rears it's head is in prototyping. We all know that when you write a prototype (or do a Scrum Spike) you are supposed to throw it away when you are finished. In the interest of finishing the prototype quickly, you probably added minimal error checking. You may have ignored boundary conditions. It may fail hard in certain circumstances. These are all valid design decisions for a prototype.

Many people looking at the value that they think is in the prototype code, are reluctant to throw away that value. So, instead of re-writing the real version from scratch, they try to clean up and fix the prototype. The result is almost always a fragile, less complete version with some of the original flaws still embedded.

Passing on the value

If you can convince yourself that the real benefit is the knowledge, not the actual code, it's easier to let go of the code itself to re-apply your knowledge in a new form. Maybe it will allow you to refactor the code more mercilessly, knowing that the knowledge will not be lost. Or, maybe you can put the whole thing aside to re-write the code if necessary.

The last effect of this change in viewpoint is to note that you are not finished writing the code until you are certain that it passes on the knowledge to the next person as well. Maybe that means you will need to improve the code structure to match your understanding. Maybe you need to add some judicious intent comments to make certain that the design decisions and their reasons are not lost. Sometimes this may even mean writing documentation to explain the design.

Whatever is needed, you should realize that only leaving the code and not the knowledge means that you are shorting the next developer the most important asset that you have made, the understanding.