On Code Comments

 Actual source code from Microsoft Word 1.0 for DOS

Actual source code from Microsoft Word 1.0 for DOS

This post is basically a bookmark for me to come back to and remind (berate?) myself regularly about my comments that I write in my code.

Not that I should do more. I actually put in a heck of a lot of comments in my code, because I know my memory is poor.  Especially so when I have done several late night programming sessions in a row.  I once even completely forgot that I had written an entire application after a month of sleep deprivation.

What prompted this post is the fact that I often find myself coming across lines or blocks of code that are commented out.  Without explanation.

Just today, I had to go back into some 2 year old code, because a client had reported a possible bug that wasn't bringing pricing across properly from their legacy system.

It took me a while to re-understand my code, and that was helped by the copious comments I had left, knowing my own mental fallibility.  However, when I finally got to the section of code that did the pricing import and looked at it, I immediately knew what I needed to do in order to effect a fix.  BUT then... I noticed that there was already two lines of code EXACTLY like the ones I was about to put in.  Only they had been commented out by me previously.

Why?? What made me comment out those two lines in the first place?  Did they introduce yet ANOTHER serious bug in the system?  There was no notation as to when the lines were commented out, nor any indication of WHY I had done so.

The 'when' is an easy fix.  I just need to go back through my version control system to work that out, but the 'why' is an altogether more puzzling conundrum.

I'll be sure to leave some comments in this section of code reiterating my journey to write, then comment out, then uncomment the alleged lines.  Perhaps in another year or so, I will come back to it and have to unravel this veritable Gordian knot of commentary.