Editor’s Note: I wanted to get this out sooner, but it looks like @roidrage published first. My opinions mirror his.

I am an average programmer. The code I write is often not elegant, nor even correct, but it works. Until recently, I rarely followed style guides or best practices; I just wanted to get a working solution running so that I could move on to the next problem.

One thing I’ve always tried to be consistent about, however, is documenting my code. That took many forms over my career, from the neverending wall of text at the start of bash scripts to hefty commit messages. In every case, the goal was to ensure I, or anyone else reading the code understood why I had made certain changes or design choices in the code.

I call it my Code Diary. I take the time during my commits to explain what changes I made and why I made them. I don’t want to waste time when I come back to the code 6 months later in an attempt to grok the reasons behind the code. I also hope they’ll be useful to others that may read the code.

To quote Mathias in his recent post:

I think about future me, future anyone who looks at my code, thinking what the hell is going on here and why?

Spot on!

A few months back, I came across Zach Holman’s presentation More Git and Github Secrets. The part that resonated with me most was the discussion about proper messages. Aside from the line length constraints recommendation, I’ve tried hard to stick to that style of commit. It helps me diarize my code.

Finally, while verbose commit messages help to understand the intent behind code changes, it’s also useful to help others reading your code understand the intent behind the code, in general. To that end I’ve started writing TomDoc-style comments above any methods I write. And hey! It’s not just for Ruby, folks.

Context is relative; the more you have the better you can reason about what you’re reading. Diarize those commits!