This is my blog about software development, mountain unicycling, Photography, and stuff I find interesting.
Friday, March 21, 2008
The Comment You Don't Want to See
Have you ever been looking through some code trying to figure out what it does and see something like this:
{ this is a bit of a hack }
This is (one of) the most unhelpful comments a person could write. Please don't do things like this in your code. Just describe why it's a hack and describe what should be done.
OK, now I feel like I am in a "one-upping" competition. I've seen both of those comments (same authors?), but this comment takes the cake:
{ Oh what a tangled web we weave when first we practice to deceive . . . }
Although I used to quote poetry / Shakespeare / song Lyrics in some of my comments, but that was hobby code that only I would be maintaining. Hmm. . . maybe I am part of the problem then.
Why have meaningless comments when you can have even more meaningless identifiers - and no comments at all?
One of modules I'm currently maintaining has a few gems - like the following three string constant identifiers. The constants contain different messages that are printed in extreme low memory situations - hence the reference to life, death and physics - I guess...
4 comments:
I once saw:
(**
Don't know why this works. Don't touch it
**)
OK, now I feel like I am in a "one-upping" competition. I've seen both of those comments (same authors?), but this comment takes the cake:
{ Oh what a tangled web we weave
when first we practice to deceive . . . }
Although I used to quote poetry / Shakespeare / song Lyrics in some of my comments, but that was hobby code that only I would be maintaining. Hmm. . . maybe I am part of the problem then.
Why have meaningless comments when you can have even more meaningless identifiers - and no comments at all?
One of modules I'm currently maintaining has a few gems - like the following three string constant identifiers. The constants contain different messages that are printed in extreme low memory situations - hence the reference to life, death and physics - I guess...
sItsLifeJimButNotAsWeKnowIt
sItsWorseThanThatHesDeadJim
sICannotChangeTheLawsOfPhysicsCaptain
Obviously the original author was a Trekkie - or maybe he just really liked The Firm.
How about this one?
{TODO: This line is still a memory leak}
Post a Comment