Improve Your Code By Writing About It

I’ve spent a fair bit of time writing articles for LiveWorks! lately – posting weekly isn’t as easy as it seems, particularly when you have three weeks leave coming up. Most of the articles include some kind of code, be it JavaScript or Java and an explanation of what the code does, why it does it and how you might use those techniques in other ways. As I go through writing the article trying to explain my code it really highlights how nonsensical my original design decisions are. Even when I’ve gone back over code and carefully refactored it to be clear, when I come to write the article I almost always rearrange things again.

Now, explaining things is well known to be a good way to get a better understanding of them yourself which is essentially what’s happening here, however I don’t see the same kinds of effects when I explain code verbally. I suspect this is mostly because I don’t want to go changing the code while I’m part way through the explanation (which would make it hard to follow) so while I might see the code smells I don’t tend to actually fix them. The other aspect is that when you’re writing an article you have a lot more time to think about it than when you’re explaining verbally. There’s not someone sitting beside you that feels uncomfortable if you just go quiet and think for a few minutes (or jump in with questions etc).

That’s not to say that verbal explanations aren’t useful – they are much quicker to do and make asking questions much easier for example. The difference is that verbal explanations provide benefits in terms of greater understanding for the listener and the explainer, whereas written explanations provide slightly less understanding – particularly for the listener who doesn’t get to ask questions – and takes longer, but provides much better opportunities to actually improve the code.

I must try to remember this the next time I need to refactor code and at least think through how I’d write an article about it, if not actually write the article.