Pixel hunts
"Hi, you found me"
An anonymous developer has admitted to writing comments in code as limericks. The confession can be found at codingconfessional.com, a site devoted entirely to divulgements of developers' depravities. Here, for example, is the limerick chap's work: “I write most comments in limerick It makes all my coworkers sick My …
When I code I drop in lines "borrowed" from 80's heavy metal and rock tracks, in addition to the proper comments. I've also borrowed lines from poems by Mike Harding. ( "Is an elephant with a runny nose worse off than a giraffe with a sore throat?" ).
No one ever bothers reading the comments anyway!
When I handed in my notice they demanded that I comment everything to the nth degree as no one knew how the hell any of my code worked and I'd written the majority of the fuzzy logic based derivations for the address matching. Inevitably there was one function that I could remember what it did, I knew it was there for a very specific purpose that applied to something that would screw up a small majority of addresses (about 0.1% of the PAF file/300k of addresses), so not having much time I simply added:
DO NOT DELETE THIS IT SERVES A VERY IMPORTANT PURPOSE BUT FOR THE LIFE OF MY I CAN'T REMEMBER WHAT
About 18 months later I got an email from one of the guys I used to work with, they'd re-written/tidied the code up and removed that particular part because they couldn't work out what it did either and from their testing couldn't see that it served any purpose. Cue using the new code for a year sending direct mail (yes I was marketing scum), and numerous complaints about addresses not being parsed properly, 6 months of trying to track down the problem to eventually find that yes indeed that line was important after all.
There's nothing more scary than a comment WARNING. Seriously. The guy put it there for a reason. He BOTHERED to tell you that it's there for a reason, or he'd have just removed it for himself. There's something VERY fragile about that bit of code that you need to audit incredibly well or steer clear of.
It's like the one that says "This function cannot be optimised. When you realise this, please increment the counter below as a warning to the next poor fellow", and the counter is called something like "hours_wasted_trying_to_optimise_this". Take the hint. Someone went to that effort, not for comedy effect, but because it serves a real purpose to do that, even in real code.
At the very least, leave it in and put in a huge damn breakpoint on that line and have it email you when it hits it. Because it'll be that one corner case that, years ago, someone realised you only hit it when the first Sunday of a leap year is the 5th and the envelopes are less than D5 size, but at that point it performs a VITAL function to correct something related only to that kind of coincidence.
Dead code is easy to detect (hell, if it's truly dead, it won't end up in the final binary - if it does, you need to find out WHY), and warning comments should not be ignored.
How bloody bad do you have to be to write code and not explain what an obscure but vital part does, and why, and how. I hit a 1:5 comment/code ratio on average for straightforward code, and where it gets complex it can easily hit 1:1 or higher. Useful stuff, not "this opens a file" crap. Stuff like links to the wiki pages for little-known algorithms, comments on performance, records of performance tests and concomitant recommendations on when to and when not to use it, what's ok for now but will need a proper fix later, even design docs if management allows time for that ... basically, whatever's necessary so the one that cometh after doesn't want to kill himself.
Clearly you are the holy grail - unfortunately the rest of us are human and make mistakes, sometimes we spend hours and hours staring at the same piece of code that *should* do exactly what we want it to - but for some reason it just doesn't. Sometimes we spend weeks trying to fix a bit of code. Sometimes we re-use old code from a different project that we know works fine - but it's been so long since we wrote it - we can't actually remember *how* it works. That being said - I doubt anyone will want to touch your code ever if it truly warrants comments *at least* every 5 lines.....
I'm all too human and make my share of mistakes. I also try to learn from them.
> I doubt anyone will want to touch your code ever if it truly warrants comments *at least* every 5 lines
You have a point. In the VB code I have to currently work on, it's pretty straightforward gui front-end 2-tier stuff and the rate of comments is lower because much of it is, or can be made to be, straightforward. Where the real grunt work is done in sql, what I said is true. If I had to do any significant middle tier work in it, that would change (which in fact will be soon).
Happens, though, that I'm working back at a place I was at 3 years ago, on some of my old code (hefty sql) and I'm grateful for the effort I put into documenting it back then. So is my boss as he had to maintain it in the meantime.
Funny how you give me teh Holy Grail snark about comments then say in the same paragraph "but it's been so long since we wrote it - we can't actually remember *how* it works" yet seem completely bloody unable to draw a straight line between those points.
...indeed.... I see your point.
Noted - must try harder to comment my code.
I suppose it's down to the coding lifecycle - quite often we are trying to get a bit of code to actually do what it is expected to (I would say supposed, but normally it is doing exactly what it is supposed to - just not what we expect it to). The problem that often arises however is: how simple is the code really?
The code at the time of writing might seem simple, especially if you have been working on similar projects in the same timespan - you might (I always do) think it doesn't need a comment because it's quite straightforward and relatively self explanatory and you'd be right. However in 2,4,8 years when you come across it and your coding style has moved on and certain bad habits have been worked on - that can often be the time when the relatively straightforward, relatively self explanatory code turns out not to be so self explanatory or simple and you being to wonder how exactly it even works.
A most civilised response.
FYI the qaulity of my commenting stems from a weakness - I'm disastrously bad at comprehending code. Unless it's written at a very high level or is very simple then I struggle. On some occasions I've looked at code I've written minutes before and said "wut?" (ok, it's always at the end of a rough day but still).
I don't know why that is, but it instills in one a nagging awareness of a potential successor's situation, which I try to pre-emptively alleviate.
And having to deal with 'exciting' code is no fun (e.g. losing 3 days to debugging because some twat didn't document that the pipe-opening convenience routine built into his framework shoved 15 extra bytes in there for reasons unknown. Just for example).
Anyway, thanks.
"Whenever I have a queue of files I prefix the field names FQ:"
All of my quicky shell scripts contain :
for f in `blah blah`
A lot of the production scripts do to! Back in the day, I was a COBOL programmer, and every one of my programs contained variables INSULT and INJURY, just so I could ADD INSULT TO INJURY.