Put the knowledge in the code

Published Nov 6, 2020

This blog post got shared in my work chat today (and everywhere else programming is discussed on the internet): Technical debt as a lack of understanding. If you read it, make sure to also watch the video, because the story of the tech debt metaphor is also fascinating. I wonder what the metaphor would have looked like if it hadn’t come out of finance….

I mostly fall into the applied mathematics software tribe. This is obvious to anyone who’s ever heard me talk about software. But, very on-brand for someone in this camp, I’d prefer to call it “reified thought” than “applied math”. So the idea of source code containing knowledge resonates with me.

This also reminds me of antirez’s “teacher comments”. Many of my favorite moments writing software have been when I learned something from the code (or the authors' comments). When I work with a system like that, it really does feel like the source code is teaching me how to think. It’s why I appreciate names and module boundaries so much. They teach me what to call something and what’s worth (temporarily) ignoring.

In some cases, probably when I’ve had too little sleep, the code can even feel like it’s designing itself. Its abstractions are so rich with embedded understanding that it feels like it knows the solution to your problem better than you do! There’s a huge “[citation needed]” there, but I don’t have any examples right now.