Why I Keep Notes While Programming

When I am deep inside a programming problem, I often believe I will remember everything. I tell myself that the reason for this strange function is obvious. I am sure I will remember why I changed that setting. I think the error message will stay in my mind because I spent three hours fighting it.

Then a few months pass. I open the project again and feel like a visitor. This is why I started keeping more notes.

The notes do not need to be beautiful. Sometimes one sentence is enough. “This library fails when the input is empty.” “Do not remove this delay.” “The server expects UTC time.” These small messages are gifts to my future self.

Programming creates many temporary thoughts. We test an idea, discover a limitation, choose one solution, and move on. The code shows what we finally did, but it does not always show why. The reason can be more important than the code.

I also keep notes about mistakes. It feels unnecessary when the solution is fresh, but the same type of problem often returns in another form. Reading an old note can turn an hour of confusion into five minutes.

There is a larger lesson here. Memory feels stronger than it is. We remember the feeling of understanding and mistake that for permanent knowledge. Writing things down accepts a simple truth: I will forget. That is not failure. It is just how minds work.