Many programmers speak truthfully of the excitement of programming. Programming evokes a real sense of discovery and a feeling of mystery at times. Things like the Tao of Programming frame it in a near mystical sense of a journey towards enlightenment. I think many of us who write a great deal of code could recall that essential feeling of joy and anticipation as we neared the solution of a given problem we were solving. We read some tricky or clever piece of code, and suddenly the whole idea clicks in our head and we feel good about ourselves and about our chosen profession or hobby. We are of course, wrong and unenlightened.
In truth, the most elegant code is that code which we read through, and feel a profound sense of boredom. We should not read through a piece of code and have the feeling of uncovering anything. A piece of code that must be "discovered" is a piece of code that is poorly written. While walking through the code along the path prescribed by the author of the code -- if the code is well written -- should invoke in us the feeling of a liesurely stroll, without any urgency, excitement, or uncertainty. There should be a sense of peace and of unhurriedness in it. If we feel rushed by a need to see what is ahead of us in our path to understand where we are now, then the author has failed to write good code. If we need to worry about what we just passed in order to do the same, the author has failed to write good code.
As authors of code, we might object the the writing of code and the reading of code are two very different things, and they are, indeed. Why then, should the process of writing the code be so readily encoded into the artifact that we ought to read. I suspect that this does little to aid us in writing good code. The good novelist does not encode all of the work of writing the novel, including all of the notes and the like, into the finished product. In some real sense, we ought not to sully the readability of our code by making a similiar mistake. We should explicate our thoughts and processes, but we should do so in such a way, and with such tools, as allow the reader to progress through them peacefully and with complete confidence.
Instead, when we are writing down a piece of code, the future reader of this code should, in a real sense, have already been impatiently waiting for this code to arrive in their path of reading, and when this code finally comes under inspection, the response should be more, "Of course, duh, let's move on," than to say, "Wow, I didn't see that one coming!" And when finally our readers are bored, we will know that we have written good code.