Making code documentation a habit

Today I opened up a project that I had not set my eyes on for over a year. Thankfully the previous developer had taken the time to fully document the code, what everything did and why it was there.

That previous developer was me. But the code could just as well have been from another person as far as I was concerned. I. Did. Not. Remember. This was the first time I was truly thankful for making code documentation a habit.

It was a private project. Nobody was going to see the code but me. It was just a small utility script of a set-it-and-forget-it kind. I had set it up, and promptly forgot all about it. It worked. I was happy.

Today I wanted to add a new feature so I opened it up again.

And the first impression was “Omg, did I really write this? I don’t recognize anything!”. But it didn’t take me long to scan the code and get familiar with what it was doing and where everything was. All because of my documentation habit.

I don’t know if you have heard of the FlyLady but my mother subscribes to her messages. They focus a lot on creating beneficial habits and routines, and one of the things she repeatedly says is that you don’t do it for others, you do it for your future self.

Today I was that future self that was thankful my past self took the time to put in proper documentation. I have made it a habit. No matter if it is a public project or a collaboration where other eyes will scrutinize my code, or a simple private script lurking on my hard drive. I document what I do. And if the file is outside source control (yes it does happen), I also write dates of when I do small changes or additions in the comments. You can even have a small revision history at the top.

Don’t do it for your collaborators.
Don’t do it for the boss.
Do it for you, for your future self.

One day you will be grateful for it