Cover image for Why you should keep a Code Journal | Code Journaling pt 1 of 4

Why you should keep a Code Journal | Code Journaling pt 1 of 4

jacquibo profile image Jacqui Updated on ・5 min read

Alt Text

Journaling is often thought of as an arty or holistic pastime, an activity for those with a creative streak or too much time on their hands. Why would a technical person be interested in journaling?

Journaling is a tool, and a Code Journal is a tool for anyone who uses technology (not just specifically code), be it in their job or as a hobby (developers, software architects, QA/testers, etc).

The stereotypical type of journaling is usually considered to be a tool for improving mental and spiritual health, the Code Journal is a tool to improve your coding and work/hobby life.

In this post I will visit a few reasons for why you should keep a Code Journal then, in the next post in this series, I will give you some ideas for starting a Code Journal. There are no hard and fast rules, your Code Journal will be tailored to you and what you need from it.

The benefits of keeping a Code Journal

Get everything out of your head

If you want to remember to do something and you want to free up your mind to do what it should be doing (thinking!) then you need to get everything out of your head. Using a Code journal for this means that you won’t lose that vitally important Post-It note with your world-changing idea scribbled on it. Your brain will thank you for letting it think, instead of remembering.

Your mind is for having ideas, not holding them.

David Allen

Track your growth

You can track your growth and see how you have improved. Without a record, it is very hard to see how far you have come. Most of us will feel we are stuck in a rut, or falling behind, at some point. Your Code Journal can either show you that you are actually improving, or it can help you identify what you are missing and to then set goals.

Track your goals and progress

You can track your goals and any progress made against them. Keeping your goals at the forefront of your mind, and keeping track of progress will move you toward your goals much faster. A Code Journal gives you somewhere to record and review your goals, to keep you on track for any deadlines set.

Pick battles big enough to matter, small enough to win.

Jonathan Kozol

Save time

Because of the records, you make in your Code Journal, it will be easier to carry on where you left off. You won’t waste time trying to remember where you got to in your project or what you planned to do next, even if there has been a long space of time since you worked on it.

Manage multiple projects more easily

It will be easier to switch between projects. Most people have more that one project on the go at a time, and looking at your last notes on a project will get you going again much quicker, reminding you what you need to look at next.

Develop a coding or working philosophy

A Code Journal will help you to develop a coding philosophy. Thinking about and analysing how you code and your own (or team/company) processes will mean you can identify what works, what needs improvement and how new ideas can fit into your coding. A more streamlined and simplified process and codebase should be the result.

Document what works and what doesn’t work

You can record things that work well or don’t work well. Having a reference for things to keep doing, things to stop doing and things to start doing will keep you on the path to improvement. Keeping a record and reviewing regularly is the key to improvement.

Keep track of decisions

You can keep track of the decisions you make about your projects, learning, etc. Can you remember why you made a particular decision, or what the decision actually was? If you now have more information, to inform that decision, you can work out if the decision needs to be revisited. You also have a reference so that you don’t have to make the same decisions again, so you’re not wasting your time.

Reduce time to market

Keep track of feature and refactoring ideas to reduce feature creep. This is an easy trap to fall into, especially in personal projects. If you keep adding new features to your current development cycle you will never deploy that app! Keeping a record of new feature and refactoring ideas will mean you won’t be worrying about forgetting your ideas and they can be considered for a future release.

Delivering good software today is often better than perfect software tomorrow.

The Pragmatic Programmer

Identify and eliminate bottlenecks

You will more easily identify bottlenecks or anything that is holding you back. Identifying things that need tweaking or skills that need to be learned will increase the speed at which you grow as a coder. Improving bottlenecks, over other areas, is likely to give you the most return on your effort.

Any improvements made anywhere besides the bottleneck are an illusion.

Gene Kim

Discover your Happy

Why do you like doing what you are doing? What is it that you enjoy? Work this out and you can focus on what makes you feel good about coding to improve your everyday happiness and help you set goals to move you further towards what makes you happy. Reviewing your Code Journal will help you work these things out much faster.

I’ve always thought people would find a lot more pleasure in their routines if they burst into song at significant moments.

John Barrowman

Gather evidence to gain a promotion or pay rise

Most organisations will require a good reason if you want a pay rise and/or a promotion. Your Code Journal is the ideal place to record exactly what you have been working on, and particularly your successes and praise from others. Don’t forget to include things from outside of your job role, such as open-source projects you may be working on. You can also make notes on your research on current market rates for your role, or role you aspire to.

Update your CV and prep for interviews with ease

Your Code Journal will be your best friend when it comes to updating your CV and practising answers for job interviews. You have a record of the technologies you have used, the projects you have worked on, problems you have solved, how you approached a difficult situation… If this list sounds a little like a question prep list for a job interview then you probably get the idea that prepping for these general interview questions by referring to your Code Journal is going to be so much easier than trying to remember everything you have done for the last x months or years.

What next?

In my next post on this series of Code Journaling, I will cover how to get started with your own Code Journal.

Alt Text

Originally published at http://www.jacqui.tk/blog on September 9, 2019.

Posted on by:

jacquibo profile



A creative and proactive software architect, encouraging an environment of communication, creativity, innovation and flexibility.


markdown guide

I haven't read the posts yet (planning to do so over the weekend) but may I suggest a small tip?

Can you mark each post as part if a series? That way Dev.to will add a nice little "widget" in the beginning of each post where people can quickly find the other parts. It looks like this:


The way to do it is by clicking the "..." icon right under the post title (in edit mode). And then giving a name to the series (in the modal):



Many thanks for that, I didn't know that setting existed.
I have been using the other editor, but found out I just needed to add Series: My Title to the bottom of the header.


I love discussions on journaling, especially in tech! I spoke at a conference in August about it. We both cover similar grounds, but I feel like you have a really wonderful way of explaining it that I still have yet to find. I really look forward to this series!


Thank you, Brittney. I have just put up the next two parts, and the last part will be available early next week.

Which conference did you speak at? I really need to get to more conferences!


I spoke at Write/Speak/Code in San Francisco. I have a blog series that I'm writing about it, but also in the process of transitioning my blog site so here's it on the old place for now:

Thanks, I'll take a look.


I'd argue that a code journal isn't the right place to 'Keep track of decisions', because I think comments in the code or an issue tracker are a better place. This way, when multiple people work on the project, other people don't have to read your code journal.

I do agree with the rest of them, especially remembering what you were doing last. I've started keeping a to-do list that was more fine-grained than the issue tracker that we use, and I've noticed my efficiency go up.


Why not both?, to me the journal is more personal, those are notes for me and probably wouldn't make sense to other, you can write things like "remmember the dumb thing you did the last time", well, the last time maybe is another project so is not relevant to others in your current project. In code comments you "translate" the journal entry in a concise and understandable version of it. In the journal you also keep discarted, dumb, far-fetched ideas and you can write 5 pages if you want, I don't care about all your process in the code and definetly not 5 pages of it. I even think that write it up in the journal first will even make better comments in your code after articulate the idea in the journal.


Hi Tijmen,
Yes, I agree, when you are working in a team then things like decisions need to be accessible to all the team. Somewhere like Confluence or a wiki would be a good place, which is a bit like a shared Code Journal.
For personal projects, though, keeping notes of decisions in your Code journal is ideal.


Hello Jacqui,

Thank you for your article on "Why You Should Keep a Code Journal".
For this reason, I have created my own code journal at my workplace :).
In it, I often write special code problems and the solutions.
It is very valuable for me.

I use Microsoft OneNote for the Code Journal.
It can be shared with my colleagues and automatically generates an index when a new page is added.


Super great post with actionable advice!


Thank you :) I hope you enjoy parts 2-4 also. Those ones are more actionable.


Great article(s), I wanted to start a journal because of "Get everything out of your head" but was almost forced because of "Keep track of decisions" It got frequent that I "fixed" some code just to figure it out why I did it the first time and realizing that now I just waster hours ruining the whole thing :) and since I started and many notepads later I really appreciate the "Get everything out of your head" part, it really feels lighter in the good way, way less clutter and noise. Those recurrent annoying ideas go away after they are written.

"Never keep in your head what fits in your pocket"
-- cant remember the author, maybe I should have written it XD


I definitely agree that "Get everything out of your head" is a very important benefit to a Code Journal. It is also the basis of GTD (Getting Things Done) and really helps you destress and become more creative.


I'm new to this but I love it! :)
Any help?


Hi Frank,

I suggest you take a look at part 2 and 3 (and 4 on Monday). Then if you have any specific questions then ask me in any of the comments :)

pt2: dev.to/jacquibo/how-to-start-your-...

pt3: dev.to/jacquibo/what-to-write-in-y...


Thank you! :)
I'd do that right away


This is just what I needed. Thank you, Jacqui. I will be looking forward to this series.