Why Keeping a Code Journal Will Help You Become a Better Developer

I’ll be honest — I straight-up stole this idea from Ryan McDermott after hearing him talk about keeping a code journal on JS Jabber and how it helped him write better code over time.

Over the past 3–4 months I’ve been keeping a code journal of my own, and I can personally vouch for the benefits that come from taking a couple minutes to reflect on the code I read/wrote. Like any habit, it takes some time to form, especially when you’ve got real work to do — and I still miss days here and there. But I wanted to share a few of the benefits that I’ve noticed.

Keeping a Code Journal Forces You to Identify Code Smells.

It’s truly rare to see a perfect codebase. If you’re working as a developer, chances are you’re spending most of your day reading code, and there’s bound to be something the code you read that’s less than perfect.

Most of the time, if it’s something that super hard to understand, you either spend a couple extra minutes reading/understanding the code, or you go and ask the developer who wrote it.

And then you go about solving the problem you were working on, and in a few weeks, you more or less forgot about the smelly code you read on that one occasion (after all, you’re on to something completely else by then).

Furthermore, sometimes you know intuitively that something isn’t clean or easy to read, but you’re not exactly sure why.

Both of these scenarios are a perfect case for keeping a code journal. By virtue of documenting what you read you’re forced to process why it was less than ideal (this has the side benefit of also exposing good alternatives), and you now have a written record that you can reference later. Win-Win.

Keeping a Code Journal Helps You Identify Clean Code.

Your reflections shouldn’t be all negativity though. Chances are you work with a bunch of smart people (I know I do!) that are capable of writing beautiful, clean, readable code.

Just like when noting code smells, sometimes you don’t intuitively know why the code you read is amazing, and chances are you’re not gonna remember it in a few weeks. Taking the time to process what was great about it will help you internalize the concepts.

Keeping a Code Journal Helps You With Personal Branding.

One of the awesome side effects of writing down all of the clean/messy code you read is that you’re basically writing outlines for blog posts. If you’re anything like me, consistency and finding good material to write on are two of the hardest things.

I’ll be honest, consistency with writing hasn’t been my strong suit, and I’m not gonna dive into that right now 😎. Keeping a code journal isn’t going to help you sit down and actually write articles. That’s more on the discipline side of things.

However, keeping a code journal can help with inspiration. Think of it this way—if you write down one entry every other day (see, even not that consistently!), at the end of a week you’d have 3–4 ideas that you can look at for inspiration. And furthermore, you’ve already written a basic outline.

Conclusion

Even if you’re not writing entries frequently, reflection is one of the best ways to internalize the things that you learn.

Another thing to note. I’ve just been using a git repo with a bunch of markdown files. I find it really easy to go write something down and get back to work this way. But you don’t have to do it the way that I do — do whatever helps you best!

What about you? Are there any specific things that you do to internalize the things that you encounter in your day-to-day learning?

Thanks a bunch for reading. Let’s connect—feel free to connect with me on LinkedIn or tweet at me on Twitter.