This article originally appeared in Dev.Mag Issue 29, released in February 2009.
I must confess. I hardly ever comment my code. It’s the sort of thing that everybody lectures about, saying that it’s important for clarity, ease of use and even national security in the event of nuclear war. This is all true (though perhaps the nuke idea was a bit of a thumbsuck) and I will always advise others to write miniature essays in their game code.
Unfortunately, I fail horrendously when I need to do it myself.
I’m well aware of the temptation to postpone commentary, skip it for minor sections, or abandon the whole idea due to a sudden irrepressible urge to pee. Of course, such thinking tends to be rather shoot-in-the-foot-ish – experience shows this. But these mistakes keep being made by many eager devvers. They seem as unavoidable as going off to play Guitar Hero when, say, one is supposed to be writing the opinion column for Dev.Mag.
Image unrelated. Promise. HAPPY PONY!
In a recent game prototype of mine – an Incredible Machine tribute containing little force balls and the Photoshopped head of an unwilling friend – I decided to see what would happen if I threw my own personality into the programming comments. Gone were the dry and crusty “//algorithm x for operation y” explanations – I took it upon myself to slip the colloquial, the abstract and the downright weird into my non-compilable statements. The results were amazing: I immediately felt motivated to comment my work more thoroughly, to think of something witty and interesting for each little code block that I came across.
I brought the “lol” back into my code. I injected some fun into tired tasks, and not only did I comment more frequently, but I started to enjoy the coding process more. Heck, none of us became programmers so that we could be bored stiff by our duties – it just happens to be an unfortunate reality that we end up frequently trawling through menu generation and file-handling procedures when we want to be doing something really cool instead.
So if you’re struggling to comment properly or are lurching through tedious code, try let go a bit and have a little fun with your work. Make wry remarks about your data structures. Express frustration, joy or relief with individual blocks. Maybe even take a step outside the comment zone and start renaming a few variables or functions instead. It’s your program. Do whatever the heck you want with it.
I’m not suggesting that you make your work incomprehensible. Far from it. You just need to realise that there’s more to coding than tiresome programming platitudes. Have a bit of fun, put a little life into your work, and remember that ifa you do something often enough, you ought to at least enjoy it.
As it turns out, this very website has – or had, I can’t remember if the value changed eventually – a style sheet that read:
width: 666px; /* Oh shi- */The site is doomed from the start.
Ponies are always relevant, though.
Sorry, but I’ve had to dig into the code of SMF (popular forum software), to write some mods or just figure out how things worked and I really have to disagree–or at least, tell you not to overdo it: Sure, have fun, but try to keep it a bit professional. For example, remarks about some library being “stupid” is just going to make yourself seem stupid if it was because you didn’t exactly understood the framework at that moment. Another thing is, this may sound weird but I found it quite frustrating, expressing condescension about particular code paths–like /* if you get here, you’ve obviously done something very stupid */ … not funny if your use-case actually happens to require that path. You know, basically, just keep it positive! Complaining in comments is never fun to read. And professionalism, if you can bring yourself to it 🙂 The occasional good joke will be even better for it!
Another thing to remember is that even if you think nobody is going to read your code, there’s still *you* in three months not having touched it, and from experience I can say, that might as well be someone else. It gets even worse when I read back code I wrote when I was quite young (well, 17/18), not only is it incomprehensible, the comments are pretty much useless as I basically just wrote whatever came up to me. It’s funny, but not if you actually want to work with the code 🙂