…I’m trying to decipher mysterious comments I left in an old piece of code. Comments that made perfect sense a couple of months ago and that were painstakingly written so they would still be clear in the future, which still despite all that end up being completely nonsensical.
About the Author
Jen McCreight (it rhymes with "write") is a geeky, nerdy, atheist feminist who managed to escape Indiana for Seattle.
Email: jen (at) thejenome (dot) com
10 comments
Remy Porter says:
May 19, 2014
“This code is horrible! What idiot wrote this? Oh… it was me. I was that idiot.” We all know that feel.
cowtown says:
May 19, 2014
http://dfan.org/writing/comment.html
Duth Olec says:
May 19, 2014
That happens to me with writing stories, actually. I’ll go back to revise it and I’ll have no idea why I wrote something. Either I’ll remove it or, more likely, only remember that it was extremely clever and leave it in despite not knowing what it means.
Nobody understands me, not even myself! Clearly I’m a genius!
… But yeah indecipherable (holy carp I spelled that right first try) code comments are probably worse. You can’t just take it out because it’s there to tell you something. To warn you. Don’t eat the yellow bread.
brendankidwell says:
May 19, 2014
Whenever you look at code older than 3 months, your old self and your coworkers are equally horrible, always.
Gus Snarp says:
May 20, 2014
Yeah. Pretty much this. Then when you become responsible for a rather large software project on which several developers have worked, all with inconsistent commenting, coding standards, etc….. ugh.
Matthew Smith says:
May 20, 2014
The best advice I’ve received regarding code commenting was to comment why you are doing something rather than what you are doing. The code itself can usually tell you what you are doing, but only you know why you are doing it.
Rudism says:
May 20, 2014
I often leave my future self little poems, musings, and jokes via comments to help soften his opinion of me when he inevitably revisits whatever mess of tangled spaghetti I’m currently weaving.
Peter Butler says:
May 22, 2014
MATTHEW SMITH has the right idea. I extend his “comment *why* you are doing something” with . . .
1) Comment *while* you are writing the code. Don’t wait for it to compile. Comment first.
2) The comments are not for you. You write comments for the person who “gets” to maintain your code after you are gone. For some reason I call this person “the turtle who cometh after.”
3) Don’t document what the code does.” I.e. in ARM assembly
add r2,r2,r3 ;add r3 to r2
is useless. I might comment “base += parameter offset” because assembly can be obtuse even with good comments.
3a) If you are doing something that is sufficiently strange that you needed serious thought then by all means help the turtle who cometh after. In 16-bit Intel assembly “ret -2” does something sufficiently strange. In 32-bit assembly the same effect is produced by “ret -4”.
It’s my guess that few Intel assembly language programmers will instantly know what “ret -2” does.
SamBC says:
May 23, 2014
Peter and Matthew have it, I think.
I would add, when you see your indecipherable comments, try to make a mental note of what it should have said, what would have been most helpful to you now – and next time, try to write a comment like that.
Commenting well comes with experience, but as you learn from mistakes, it has to come from experience of dealing with crap comments.
A Kaleberg says:
Jun 12, 2014
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.