I never hate my past self more than when…

What do you mean the comments aren’t for you? I write my comments first. Usually I come up with some great idea for some code and write a whole pile of comments which I type up as fast as I can. Then, I usually realize that some of the comments don’t make any sense, or worse, are of the form, :then a miracle occurs” which means I don’t have a clue as to what I am doing.

Eventually, I start writing some code because the compiler is just going to laugh if I dump in a program full of comments but nothing to execute, and it’s going to laugh enough at my code even after it’s working. (Compilers have a vicious sense of humor in my experience.) Eventually, the code works and the comments sort of describe what it does. I usually leave in the comments about a miracle happening, except I try to explain how the miracle works in as much detail as I can muster. It’s great living in an age of wonders.

If I don’t comment first, I usually forget my great idea about structuring the code before I get halfway through. All the details of coding take up the working memory holding my brilliant design, and let’s face it, coding is full of details. (See, then a miracle occurs, above.)

Of course, the real trick to writing code that one will be able to understand in ten or twenty years is to write really boring code. If you always use obvious iterations, a standard set of names, and try to do the job with a bare minimum of cleverness, you are much less likely to outsmart yourself. Decades ago, it really made sense to bum every cycle I could squeeze out of my code, but for the last 20 years or so I haven’t bothered.