jump to navigation

Bad encounters with programming guides May 5, 2011

Posted by mareserinitatis in computers, engineering, research, science.
Tags: ,

Like almost everyone who has experience writing code, I’ve been guilty of doing a crappy commenting job.  I write a piece of code and go back months or years later to realize that I have NO idea what I did and nor does anyone else.  Thus, I am now at the opposite end of the spectrum.  There’s a loop of some sort, there’s a comment explaining what it does.  If there’s an equation I’m solving, the equation is in my comments.  If I pulled material, such as an algorithm from a book, information on the book, including the page numbers involved, are added to my code.


As you may guess, I now hold everyone to those standards…and their code almost never holds up.  However, there are different levels of crappy code.  Specifically, there are three of them.

The least offensive level of crappy code is that which is reasonably well-commented but has stupid variable names like Fred, Wilma, Betty, and Barney, i.e. names that have no bearing on what the variable actually does.  I almost never see this.

The second level omits these useless variable names, choosing instead to use names that actually relate to their functions.  However, comments are sparse, at best.  If you have good familiarity with the algorithm, there’s a chance you might understand it…maybe.  This is actually most of what I see.

The third and most egregiously awful level combines both of the worst aspects of the coding errors mentioned above: no commenting and nonsensical variable names.  When you ask the person how other people are supposed to keep track of their code, you’re told you simply need to know how it works.  I’m not normally a violent person, but it is infuriorating enough to make me want to throw my favorite software engineering text at them.

So please – if you’re writing code, please do an adequate job of coding AND use appropriate variable names.  I’m too short on books to lose too many.



1. Fluxor - May 5, 2011

I’d think the most offensive code is one that doesn’t work.


2. GEARS - May 6, 2011

^True dat.

I never comment because I couldn’t be bothered. And now that I’m working on a paper with DrWife and she 10fold the matlab guru that I am, and she comments like crazy, it’s a pain in the ass… On the flip side, she used variable names that are waaaaay too long like “X_linear_displacement_nm_for_underwater_basket_weaving”. I guess we’re both guilty of improper coding.

But yes, I agree it’s necessary.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: