It feels like whittling. Even though “construction” is the most frequently used metaphor for trying to describe what we do all day at work, it doesn’t feel right. I also don’t know why we only use wood-working metaphors. Any psychiatrists in the house?
It feels like whittling to me because of something called “composability.” Composability is all about combining pieces of code to create something bigger, that does more work. There are several ways to do this, and times there are very real technical challenges. But this is a lot harder than it sounds.
When we think of construction the first attribute we think of is its composability. Any weekend warrior can go to Home Depot and get what they need, and so long as they’re paying attention, asking the right questions, and checking the specs—all the pieces will work together very nicely. As a software engineer that would be amazing. I dare to say we experience the opposite.
Very few things “Just Work”. Many commentators have lamented that a lot of programming tasks “these days” are just writing “glue” code to put various things together. I don’t disagree, but I also don’t think that is a Bad Thing™️, and its not easy to do well either. Because composability is hard.
In fact, its so hard there are many times we have to pass on re-using working services and code because retro-fitting it to our new purposes would actually take longer than just doing it over, precisely the way we need it. Composability can be harder than making something brand new.
This is why I chose whittling as my metaphor. Sometimes you get to simply take something you’ve already done and re-use it, whole-cloth. But, more often than not, you have to start from a blank slate, and mold the code/chisel the piece of wood until it works/looks just the way you need it to for what you’re doing.
Read more: What Building Software Feels Like
I don’t think I have to convince anyone that reading code is hard. Often its so hard we throw up our hands and rewrite it. There is a saying that “tech-debt is any code that you didn’t write”. Because reading code is hard.
I don’t think I’m going out on a limb when I say: rewriting shipped-and-working code just because you find it hard to read is absolutely the wrong move. You are actively destroying learned knowledge embedded in that code. Knowledge is value.
Engineers who know that learned knowledge is value document their code. They document code because reading code is hard. Reading sentences describing why the code does what it does is easy. That is a way to protect your code from being rewritten and discarded—a way to protect the value you’ve created through your learning. When you find yourself learning about why an existing piece of code does what it does, and there isn’t documentation—go ahead and document it. Even without changing code you can add value to it.
I have the good fortune to be volunteering some time helping folks learn to code. I’m coming to a realization that—they actually know how to “code”. Or rather, they know how to think through a problem in its constituent steps. And they can break steps into smaller steps. What they don’t know is “how to speak computer”. The syntax trips them up constantly. And they don’t have a good map of concept—>syntax. This is why reading code is hard. And its why junior engineers out of college have, largely, the same problems. They may be better with syntax purely out of having spent more time with it, comfort, but they still lack a map that translates a concept into syntax. That is something that comes with confidence and experience.
When people say “Good code is eas(ier) to read” they aren’t saying that reading code is hard. They are saying that; this code is probably documented, and this code clearly demonstrates the concept the code is implementing. Bad code obfuscates what is really happening. Good code makes it front and center. Good code plainly states what was learned in order to write it and why it was written.
Read more: Reading Code Is Hard