O Code, Where Art Thou

Or how to wrangle insights from a massive codebase…

Music is a core part of my being. I have been a heavy metal musician, a college radio DJ, and traveled hundreds of miles to see my favorite bands. At my peak music obsession, I once had a collection of over 2,000 CD’s featuring over 20,000 songs.

Movies are also a big part of my life. When I find a combination of a great movie with a great soundtrack, the soundtrack is on repeat play for months on end. That was what happened when I watched the Coen Brother’s film O Brother, Where Art Thou and fell in love with the classic Americana folk music weaved throughout the movie.

One problem that comes with having a vast repository of music is that it is easy to forget songs and bands. There have been plenty of times when I would hear a familiar song and then wonder who did that song. Unless I am lucky enough to whip out my Soundhound app before the song ends, I am tortured for the rest of the day trying to recall the song.

That was the premise of a recent Reply All podcast episode. A listener called up asking if a popular song could possibly be erased from the Internet. His recollection of the tune was so detailed, he was able to direct a bunch of professional musicians to recreate a half-way decent version of the song.

I won’t spoil the ending, but popular songs do vanish from music history. Similarly, there is plenty of human knowledge that goes by the wayside, tossed away and never to be found again. We try to address this through wikis and documents and videos, but still manage to lose much of the context.

Facts are helpful, but what is more important is the backstory. For example, a laborious process at work that no one remembers why it exists or a tool you are still paying for but forgot why it was originally purchased (happens all too frequently in most companies).

The same happens to code. The problem is not so much that you forget the code, though that certainly is an issue with large codebases. It is more the case that you forgot what the code does or why certain decisions were made. Rarely does developer oriented documentation exist, so developers are left to sift through the sparse smattering of code comments, git history, and bug reports to get context.

Code comments deserve special attention here. This is because comments can have the opposite effect of providing context:

The developers are biased for being the authors, they don’t have the capability of judging their own work from an outsider perspective and that will lead to comments that other developers will find it hard to read.

We often forget as developers that the code we write should be able to explain how the code should work. In other words, if we have written clean, legible code, that should be enough for other developers to understand. Good code is self-documenting.

What code cannot easily explain is the “why”. That is analogous to unwritten rules, bad processes, and old files. We can see what it is, but we have lost the context behind the code. Context manifests itself in the following ways:

  • Value — what does the code add to the overall functionality of the product, how is it contributing to usability and business expectations, is it still useful,
  • Impact — how does this code impact other aspects of code and functionality, what other code does this piece of code depend upon,
  • Quality — does the code produce proper and expected results, does it contribute to maintainability, has it been tested and verified.
Image for post
Image for post
Image for post
Image for post
Image for post
Image for post

Episode #3 — Ross Clanton on roadblocks & roadkill in DevOps adoption

Thoughts on developers, digital transformation, enterprise agility, community building & software engineering culture. Author 👉 https://twitter.com/marksbirch

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store