A Microsoft blogger, Matt Warren, has a great piece entitled Programming in the Brain, describing how he reads code.

It’s a beautifully written piece — go on, go read it if you haven’t yet. What strikes me most here is that what he describes isn’t detailed understanding, dissection of code. He’s just reading it.

Now, firstly, I’m so glad that someone else admits to doing this. To seeing code as art, as a map, as a story. Personally this is how I approach code — I can always delve into the details, manual in hand, to work out exact what is going on. But what I really want is the sense of what’s going on. To take 2 steps back and see the design. See the what, not the how.

This is what we should be thinking of when writing and documenting code. Think of the people who will come after you and only want to change one thing, or fix one problem. Help them read your code as a design, so they can tinker where they want, improve what they need to. Make it beautiful. If we all did a bit more on this, we’d all have more time to create as maintaining and using existing work would be so much easier.