Seahorse Tail fractal by Wikipedia user, Wolfgangbeyer CC-BY-SA
What is high quality code?
I have been asked this question now a couple of times in my current job search. I usually go back to my thoughts on functional decomposition. I like the concept but that phrase is clunky. It doesn’t help explain the concept very well.
As readers of the site know, recently I have been walking more in an effort to improve my health. For a longer time, walking has been a large part of my experience of travel. My favorite places to visit are those that are highly walkable. I suppose that is why I fell so hard for the few great European cities I have managed to visit so far. Most recently I spent a fair amount of time walking around Cleveland with a close friend, seeing that city through his eyes.
Like a lot of American cities, I noticed how distance in and around Cleveland works a bit differently than in the old world. To get from one part of a sprawling America metro area to another, often you have to take a car or some other form of transport like light rail or bus. The best America cities, as in Europe, are very walkable once you get to a specific part.
During this most recent trip I really dwelt on the different experiences of the same place when walking versus riding. Driving around, the scale of the place collapsed. Place names were much more shorthand labels than something I got any direct visceral sense of. I might see a storefront but it was there and gone too quickly for me to see into the interior, see the people inside, or any other specifics. I could form a very rough map of the overall city but could not yet identify with its districts and neighborhoods.
Once we got out of the car and started walking, my perspective shifted. The character of each district emerged in the how the various business, buildings and open spaces were arranged in close relation to each other. Architectural themes became more clear, revealing more detail and texture. Individual people, groups and crowds made more of an impression. Everything opened up, feeling a lot bigger. The other place names on my mental map receded further away in favor of the scenes right in front of me. Conversation with shop owners, restauranteurs and citizens became possible, filling in more of the narrative sense of place than the useful but necessarily brief sketches my guide gave me on the way in.
Even more recently, I took a walk through a well known area park that happens to extend right up to within a block or two of my home. The park is named for a creek that meanders through it and the foot paths closely follow the aimless curves the running water takes. I love walking with the sound of running water nearby. I took my ear buds out and left them out for most of my walk. Like the sense of expanding scale I felt during my week in Cleveland, my sense of the neighborhood opened up, through sound, sight and sense of distance.
I walked about to the nearest shopping plaza and back. By mileage covered, I actually walked at least twice as far as the straightest distance between there and my house. Walking through this stretch of green space right through in the midst of an active DC suburb, it felt like ten times as far. I realized how much I had been taking that distance for granted. I usually cover it in my car, in trips measured in tens of minutes rather than the hour my walk took. That walk covering the same area and a comparable distance felt like an entirely different scale.
I think there is a closer parallel revealed in the best written source code. High quality source code is like a fractal. The more you zoom, the more detail is reveal. That detail doesn’t have to be self similar, it usually isn’t. What emerges the closer you look is more like Mandelbroit’s more complex fractals, like the one pictured above.
When reading to get the general sense of a program, it should feel like driving through a city scape, taking in more of a gestalt than any specific surface detail. A reader should be able to grasp the general orientation of the code. This module does this, that subsystem does that. More specific details should be easy to ignore, behind API boundaries or at least in different but well laid out source files. The placeholders and map should cover just the broad functions, responsibilities and relationships of the code.
When troubleshooting, especially in an interactive debugger, it should be possible to walk down into the code to focus on a specific neighborhood to the exclusion of the rest of the code. That overall map may still be in mind, but it should feel comfortable and natural to just take in the local concerns without needing to know anything more specific about more distant code. If distance code intrudes, odds are your bug is going to be much, much more difficult to isolate and to fix.
When writing high quality code, think about the experiences you have that reveal different senses of scale for the same thing. For me, walking is one activity that helps me grasp this idea on an intuitive level. No matter how fast I walk, or even if I decide to run, the zoomed in sense of scale remains. I have to express a concrete intention to trigger a shift in scale, by getting in a car or a bus.
If you can use the tools your language and technology of choice provide to cultivate that same possibility of overlapping, simultaneous but different scales, then I think you are on to something. In my experience, code that works at various scales is easier to test, to read, and to troubleshoot.