I’ve been going through my old notes and found this section: “How to write a programming journal” written on 8th July 2018.
This was when I had decided to start daily journaling about programming topics and challenges I’ve encountered (although I had skipped many days and stopped altogether at the end of the year).
I likely had done some research on writing a programming journal may have copied some of the content on this post. I can’t remember whether I wrote my own take on the research I did on this or whether it is a direct copy-and-paste. Regardless, I’ll share my notes here.
The Benefits of Journaling 📓
🤔 It helps you articulate your thoughts.
If you’re like me, you probably tend to “think through” your coding problems. Trying to implement an algorithm? You run each step through your mind. Need to design a new class? You sit in front of a blank class file, thinking about what variables and methods it’ll need. Stuff like that.
And that’s fine for small stuff, but can be unwieldy — even counterproductive — when you have to tackle something more advanced and/or complex.
That’s when a journal comes in handy. It gives you a place to work through your thoughts (e.g. algorithm steps, design process, or whatever else) in a concrete way. You can see everything before you. Not only does it make you less prone to errors, but it’ll help solidify those concepts in your mind.
💪 It can make you more productive.
The above-mentioned process of “unloading your thoughts” is more important than you might realize. As it turns out, the simple act of jotting down a task/problem/thought can free up your mind and improve your concentration.
For example, unloading the details of that newly-designed algorithm into your journal can let you focus on other tasks without wasting “brain CPU cycles” on keeping those details at the back of your mind.
A journal also forces you to slow down and think. It’s tempting to rush into an implementation, and sometimes that works out fine, but you’ll be better off if you think through the entire solution before you write even one line of code. One hour of planning can prevent many hours of debugging!
📈 It records a history of your progress and development.
This may be the biggest benefit of journaling, especially for new coders. The hardest part about being a newbie is being blind to your own progress and feeling like you aren’t moving forward. But each journal entry represents a discrete achievement. It feels good, and that’s priceless when learning.
It’s also useful for staying motivated on long-term projects because the journal acts as an objective reminder of how far you’ve come. When you feel like you aren’t making progress, the journal tells you that you have — and that can be a great motivating boost.
Lastly, a journal can be physical evidence when you run into patent or copyright issues, but only if you date and sign your entries. This probably won’t be much of an issue unless you work on big projects with millions on the line, though.
What to Write in a Programming Journal 📓
📆 Date and signature
Always date your entries for posterity. If your note-taking app can do it automatically, even better.
⁉ Problems encountered
When you run into an evasive bug or a conceptually-tough algorithm, write about it. Start with a description, when it seems to occur, and a list of possible causes. If you can reproduce it, include those steps. Sometimes the act of writing these things can lead you to a solution.
🎉 Solutions explored
As you try to solve the problems above, record your attempts to fix them. If the solution works, great! If it doesn’t, record why it failed. If a solution is suboptimal, make note of the shortcomings so you can iterate later.
This methodical approach to bug-fixing is extremely helpful, especially when you’re first starting out and feel overwhelmed by a bug or algorithm — but veterans can benefit from this too.
📝 Log your successes
Keep a separate list of every win along the way, perhaps in the back of your notebook. Did that algorithm finally click? Or maybe your five-day search for a bug finally paid off? Write those wins down! Later, when you’re feeling stupid or unproductive, you can refer back and see all of the things you’ve accomplished.
It’s a simple thing, but can have huge results. I’ve personally found it effective in defeating programming burnout. And as your “Hall of Successes” grows longer, it becomes more powerful as a reminder of your skills and progress.
🤓 Things to revisit later
A bug-tracker might be better for tracking todos and bugs (duh) but a journal can be great for jotting down concepts, algorithms, questions, topics, and other “things” that you can’t look into right now but want to research later.
🥇 Ambitions and goals
This one’s not so much about programming as it is about your future as a programmer. Where do you eventually want to end up? How did today’s session or this year’s project take you toward that goal? Or did it set you back? These kinds of entries can be great for re-centering yourself and your direction.
🤦 Lessons learned
After every session, it can be nice to recap everything you did and think about what you learned. Similarly, you should think about recapping every major milestone on your current project and the lessons you’ve learned. This is why developers do post-mortems — by articulating lessons learned, you’re more likely to remember them going forward.
Summary 📝
While I hadn’t written in my programming journal in a while, I can see why it can be useful, especially if you’re a junior.
I’ve been reading back on my old journal entries written in 2018. It has some notes I made of concepts or questions I had, notes of events of that particular day and how I felt on those days including decisions that were made by the team or by management. Its a great way to see how I’ve grown since writing those entries.
I don’t know whether I’ll start journaling again but in many ways, these blog posts I’m writing are a form of journaling for me. I enjoy writing them as well as reading through them retrospectively. I may start to go through my old journal entries and create blog posts on the ones I think would be good to share.