Comment On Coded to the Letter

Let's hear it for the least possible effort. Compliant, but meh...

When I see something like this I wonder: is the coder stupid? Did they truly not understand the point of the coding standard? Or are they deliberately trying to undermine it?

They won't let you name an array nouns and then cycle through it naming each of its members noun? WTF? Naming arrays in the plural of what they store is one of the easiest and most intuitive variable naming conventions there is...

This is an awesome WTF. Code worked before, code still works just fine. Some might say an elegant, simple hack...others would call it a travesty. And there's almost a bit or sarcasm thrown in. It took some lateral thinking skills (and some big gonzagas) to recognize that T and L are only one letter apart, but TT and LL would be two letters apart and yet add absolutely zero information to the variable names.

I don't know whether I want to smack the coder or buy him/her a beer.

CAPTCHA: slashbot

Aside from the use of capital letters for variables, and the use of single-character variables outside the scope of temporary variables (i, j, k for iterators, etc)....I don't see the problem.
.
.
.
Oh...wait, that's plenty.

jaspax:

When I see something like this I wonder: is the coder stupid? Did they truly not understand the point of the coding standard? Or are they deliberately trying to undermine it?

I disagree, he did understand the point of the coding standards. They had coding standards, he revised his code to those standards, what's wrong with that?

I say it's their fault for not adding an additional rule:
3. Variable names should be descriptive.

In which case he'd have had to name his variables.

int Top, Left, Width, Height;

viola, problem solved, new coder learns.

While the more-than-one-letter rule sounds reasonable when you explain it in terms of "day" vs "days", and these particular variables should be descriptively named, the rule actually forbids single-character names altogether, even when they would be reasonable to use (for example, if you have 'i' and 'j' for nested loop counters)

Welbog:

They won't let you name an array nouns and then cycle through it naming each of its members noun? WTF? Naming arrays in the plural of what they store is one of the easiest and most intuitive variable naming conventions there is...

Dead easy:
Nouns and noun. Or, if you use nouns more often: nouns and Noun. Bam. 2 letters difference :)

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

What the heck is wrong with that?! (The original, as well as the amended version.) Crazy coding standards.

When you see the four letters T, L, W, and H, all declared in the same statement, intuitively almost anybody can (should) link them to top, left, width, and height. Assuming the method deals with positions of some sort, those variables should lend their names even further to their purpose.

My point is, there's got to be a balance between "Yes, this is a good coding practice" and "It's blinding fucking obvious what's going on here."

captcha: darwin... Maybe these people will evolve one day.

stevekj:

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

I'm not sure, I think it's the setup for a joke. I first found it in the Wizardry series of comedic fantasy books (made of awesome), but I'm sure its roots lie elsewhere.

<person1> BlaBlaBLABLAblablaaaablaBLA, and viola!
<person2> It's voila.
<person1> Not the way I play it!

Single letter variables shouldn't be acceptable anyway -- even as temporary loop iterators. Its silly and ambiguous.

Vector:

My point is, there's got to be a balance between "Yes, this is a good coding practice" and "It's blinding fucking obvious what's going on here."

For real. T and L may be a bit of a stretch for people who haven't done much graphics/windowing programming, but W and H are pretty straightforward.

Following the coding standard and calling them "Width", "Height", etc. may improve readability a bit, but not enough to make it even worth mentioning.

This is just some guy trying to get his damn work done without being bothered by some overly-specific coding standards.

FeepingCreature:

stevekj:

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

I'm not sure, I think it's the setup for a joke. I first found it in the Wizardry series of comedic fantasy books (made of awesome), but I'm sure its roots lie elsewhere.

<person1> BlaBlaBLABLAblablaaaablaBLA, and viola!
<person2> It's voila.
<person1> Not the way I play it!

Doh!
Those two words should have at least a two letter difference!

If only english followed such strict c0ding standards...




As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I'm a desperately bad typist but even I think it's worth the couple of extra seconds to name things descriptively.

IMO code should be as easy to understand as possible. Not everybody that will ever work on it is as smart as you are (including yourself 9 months, 18 months 3 years later when you go back to it).

Yes that can include 'pointless' variable declarations and assignments rather than jamming nested function calls onto one line. The compiler will (more than likely) work it out to nice efficient code. Can also be a godsend for step-through debugging.

Obscurantism drives me nuts. Tend to think it's usually some job-preservation thing :-)

Strider:

FeepingCreature:

stevekj:

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

I'm not sure, I think it's the setup for a joke. I first found it in the Wizardry series of comedic fantasy books (made of awesome), but I'm sure its roots lie elsewhere.

<person1> BlaBlaBLABLAblablaaaablaBLA, and viola!
<person2> It's voila.
<person1> Not the way I play it!

Doh!
Those two words should have at least a two letter difference!

If only english followed such strict c0ding standards...




As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I've always thought i, j, k was borrowed from ijk vector notation from Maths.

I dunno. I'm kinda split on this one...

in this case, I'd say a comment explaining what each one is should be enough. there are exceptions to every rule. Also, I say smack him AND THEN buy him a beer.

bobday:

Following the coding standard and calling them "Width", "Height", etc. may improve readability a bit, but not enough to make it even worth mentioning.

I disagree - if you call your variables "width", "height" etc, you can leave out the comment. This removes one more case where your comments and code might get out of sync, so it'll be easier to maintain that code.

Of course, in that case I would object more to the requirement that you need to add a comment just because the coding standard says so. Comments that don't add any info only reduce the readability - and readability should be the prime concern of a coding standard.

Personally, I'm not in favor of too rigid a coding standard anyway, there are always exceptions where deviating slightly from the standard creates more readable code.

Vector:

When you see the four letters T, L, W, and H, all declared in the same statement, intuitively almost anybody can (should) link them to top, left, width, and height. Assuming the method deals with positions of some sort, those variables should lend their names even further to their purpose.

What about when you see a single T, a hundred lines of code later?

I mark first year java at a university. I see this type of crap all the time.

int sa; //Student age
int da = 19; //Drinking age
...

50 lines later

if (sa >= da)
serveOrder();
else
denyService();

-25% Variable Naming!

"y u mrk var names down?" (Yeah, I get this type of email all the time. Pathetic)

"Because I don't have a clue what sa or da are!"

"but i say so in comment"

I also run across a lot of arrays:

int a1, a2, a3, a4, a5, ..., a10;

I suppose this technique is good because it forces loop unrolling, which optimizes the compiled code. I also avoids any confusion over zero-indexing.

Strider:

As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I've always assumed "i" is short for index, or iterator. Personally, I never use "j". For nested loops I go with "ii". Of course there's only one letter difference from "i", but they're distinguishable from each other at a glance.

"It's blinding fucking obvious what's going on here." is a very subjective observation. What is perfectly intuitive to one coder may be absolutely obscure to another.

Coding standards are engineered with the goal of making code universally-intuitive. This is not to assert that they always achieve that goal, but so it goes.

I hate to use this phrase about developers, but you really have to pitch to the lowest common denominator. Otherwise, what was fantastic code while you were maintaining it will one day show up on WTF after you leave and somebody else has to figure out what's going on.

Caffeine:

Strider:

FeepingCreature:

stevekj:

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

I'm not sure, I think it's the setup for a joke. I first found it in the Wizardry series of comedic fantasy books (made of awesome), but I'm sure its roots lie elsewhere.

<person1> BlaBlaBLABLAblablaaaablaBLA, and viola!
<person2> It's voila.
<person1> Not the way I play it!

Doh!
Those two words should have at least a two letter difference!

If only english followed such strict c0ding standards...




As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I've always thought i, j, k was borrowed from ijk vector notation from Maths.

i stands for iterator and it's only logical to use j and k if i is already in use, just like if you can't use x you use y and z.

Also, use a better font.

Micro:

This is an awesome WTF. Code worked before, code still works just fine.

Not if he forgot to change the names elsewhere in the code...

Captcha: craaazy

Welbog:

They won't let you name an array nouns and then cycle through it naming each of its members noun? WTF? Naming arrays in the plural of what they store is one of the easiest and most intuitive variable naming conventions there is...

This was my reaction too. And since, in that case, 'day' and 'days' will be different types, the compiler will complain if you mess them up. (Assuming a statically-typed language.)

Hk:

Dead easy:
Nouns and noun. Or, if you use nouns more often: nouns and Noun. Bam. 2 letters difference :)

You're probably sarcastic, but that's even worse.

k:

I'm a desperately bad typist but even I think it's worth the couple of extra seconds to name things descriptively.

...

Yes that can include 'pointless' variable declarations and assignments rather than jamming nested function calls onto one line. The compiler will (more than likely) work it out to nice efficient code. Can also be a godsend for step-through debugging.

Obscurantism drives me nuts. Tend to think it's usually some job-preservation thing :-)

I'm all for your example of 'pointless' variable declarations, but I tend to be of the opinion that longer names are not necessarily better. A loop with an index i probably is better than a loop with index currentRowIndex. Even i and j for row and column is okay, though for that I tend to use r and c or even row and col. If you have three loops, or two loops with different meanings, then you should add a couple letters.

Addendum (2007-08-02 10:54):
"If you have three loops, or two loops with different meanings, ..."

...or a loop longer than a few lines. Forgot to say that before.

Why not use for example loop vars like col_index and row_index, or xxx_idx if u r lazy?
This is much better than i,j and k.
Btw, the coding standards of that shop suck. The could not write a rails app when they prohibit pluralizing variable names. And commenting variable names is stupid too because one should better find a meaningful name for a variable than adding comments to describe what int abc45 does.

jaspax:

When I see something like this I wonder: is the coder stupid? Did they truly not understand the point of the coding standard? Or are they deliberately trying to undermine it?

If the coding standard said, "Variable names should be descriptive", you would have a point.
But that is clearly not the intent of the people who made this standard; the intent of the people who made this standard seems to have been to, well, HAVE a standard.
"Look at us!! We have a standard!! I'm an Architect!!"

Tools like that need to be mocked and undermined at every possible opportunity.

Frank:

Why not use for example loop vars like col_index and row_index, or xxx_idx if u r lazy?
This is much better than i,j and k.
Btw, the coding standards of that shop suck. The could not write a rails app when they prohibit pluralizing variable names. And commenting variable names is stupid too because one should better find a meaningful name for a variable than adding comments to describe what int abc45 does.

I try to ensure that the standard says "comments can be placed here" rather than "comments are required here", in other words a comment isn't required, but if there is a comment, it goes in a particular place or has a particular decoration (e.g. doxygen markup, or C-style comments only in mixed-language header files).

It makes no sense to write:

// loop counter for the only loop in this 10-line function
int loopCounter;

It would be better for readability to leave out the comment above, since the comment simply decreases the signal-to-noise ratio by 10%.

OTOH it makes some sense to write:

// note that "42" is no longer a legal person number (see bug 363)
int personNumber;

assuming your language doesn't allow you to code that restriction directly, and also assuming that there isn't a more pertinent place to put that comment, such as right before the line where personNumber == 42 would start to be a very bad thing.

Come to think of it, I've been trying for a few minutes now to think of a case where it makes sense to restrict the positioning of comments (other than whether they are permitted on the same lines as code, or must appear on separate lines), and I can't. Comments need to be where people will be looking when they are reading code, so their positioning depends entirely on control flow and not on some arbitrary standard.

Vector:

When you see the four letters T, L, W, and H, all declared in the same statement, intuitively almost anybody can (should) link them to top, left, width, and height.

I always think "Tea, Latte, Water, and Hotchocolate", myself...

Slasher:

Caffeine:

Strider:

FeepingCreature:

stevekj:

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

I'm not sure, I think it's the setup for a joke. I first found it in the Wizardry series of comedic fantasy books (made of awesome), but I'm sure its roots lie elsewhere.

<person1> BlaBlaBLABLAblablaaaablaBLA, and viola!
<person2> It's voila.
<person1> Not the way I play it!

Doh!
Those two words should have at least a two letter difference!

If only english followed such strict c0ding standards...




As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I've always thought i, j, k was borrowed from ijk vector notation from Maths.

i stands for iterator and it's only logical to use j and k if i is already in use, just like if you can't use x you use y and z.

Also, use a better font.

Are you sure i doesn't stand for index? :)

I agree about using a better font - on windows, the Consolas and Anonymous fonts looks pretty good.

This must be the first time that the comments would have made for better code than the code itself!

I am working on a program that was coded by a guy that was completely incapable of using good, descriptive variable names. Also, he would abbreviate words just because he didn't know how to spell the full word in English.

Just the word 'exist' has been spelled in 5 or 6 different ways, it drove me mad. Try a search and replace on exists, escist, exsists...

Welbog:

They won't let you name an array nouns and then cycle through it naming each of its members noun? WTF? Naming arrays in the plural of what they store is one of the easiest and most intuitive variable naming conventions there is...

I definitely agree. I've declared many an array as the plural of it's contents.

babbitt:

Aside from the use of capital letters for variables, and the use of single-character variables outside the scope of temporary variables (i, j, k for iterators, etc)....I don't see the problem.
.
.
.
Oh...wait, that's plenty.

I don't like things like i & j for loop iterators--the iterator should be named related to what's being looked at. There is one perfectly legit case, though. When you are dealing with graphics is it not sensible to have x and y coordinates??

Beowulff:

bobday:

Following the coding standard and calling them "Width", "Height", etc. may improve readability a bit, but not enough to make it even worth mentioning.

I disagree - if you call your variables "width", "height" etc, you can leave out the comment. This removes one more case where your comments and code might get out of sync, so it'll be easier to maintain that code.

I definitely agree. My philosophy on coding is virtually zero comments. If a comment is needed that normally means the code isn't clear enough. This does occasionally mean extra procedure calls for no reason other than naming what I'm doing but the runtime cost of that is trivial.

The rule sounds a bit stupid to me. What's wrong with ...

foreach (Day day in days)
{...

I agree with the coder.

Strider:

As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

Only if you're using a font that is completely unsuitable for coding. If that's the case, you're likely making other mistakes too, like O/0 or i/|/l/1. Choose a font suitable for coding before you damage your team's productivity any further.

Strider:

As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

In Fortran IV & 77, variables starting with I-N were implicitly defined as INTEGERs, all others were REAL. So, naturally, when you needed to iterate loops, you used I, J, K, L, M, and N. Of course variable names were limited to 6 characters so having decently descriptive variable names was difficult.

kastein:

I dunno. I'm kinda split on this one...

in this case, I'd say a comment explaining what each one is should be enough. there are exceptions to every rule. Also, I say smack him AND THEN buy him a beer.

No get him the beer first then hit him when he is drunk

Beowulff:

bobday:

Following the coding standard and calling them "Width", "Height", etc. may improve readability a bit, but not enough to make it even worth mentioning.

I disagree - if you call your variables "width", "height" etc, you can leave out the comment. This removes one more case where your comments and code might get out of sync, so it'll be easier to maintain that code.

Exactly. If you *need* to comment your code to make it readable, you aren't writing good code. Requiring that users comment their variable declarations only encourages crappy variable names.

I agree, and it's not hard to pick the right font at all, as proven by the fact that the font of this forum is perfectly capable of correctly displaying all the different characters you mention.

I really really don't get that coding standard. It's completely useless, and most languages don't follow it [and-end, if-in, for-or].

The stated justification (avoiding single character typos) is met by the hack, when in reality the problem is better met by the "use descriptive variable names" standard suggested by another commenter.

If I saw this "one letter difference" in a coding standard, I would not work for that organization, especially if the A-R jerk that came up with it was still working there in a position of influence.

I disagree that comments are NEVER needed.

If your code is well written and descriptive, comments may not be needed to tell you WHAT the code is doing, but they are extremely helpful when you need to know WHY the code is doing what it is doing.

That isn't always immediately obvious in the case of bug fixes, workarounds, and things that are done because of stupid policy decisions that overrode sane technical practice.

As clear as you think your code might be, it is never going to be immediately transparent to even the sharpest coder who tries to maintain your code. Do them a favor and provide a heads up.

Captcha: cognac. Sure could use one right now!

EvanED:

Welbog:

They won't let you name an array nouns and then cycle through it naming each of its members noun? WTF? Naming arrays in the plural of what they store is one of the easiest and most intuitive variable naming conventions there is...

This was my reaction too. And since, in that case, 'day' and 'days' will be different types, the compiler will complain if you mess them up. (Assuming a statically-typed language.)

...and assuming that the expression isn't equally valid in both cases.

I've lost count of the number of times I've caught code like:

// C++ constructor for class Foo which has member 'days'
Foo::Foo(const Day &day) : days(days) { ...

which is valid C++, and makes sense in one important case (which is why the standard requires it--it provides the only way in C++ for an object to be constructed with a member reference to *this from an argument)...but is nonetheless completely wrong most of the time it occurs.

i is the first variable name that's implicitly of integer type in Fortran. That is why it's so popular as a loop index among old-school programmers. And the rules about which variables are implicitly integer in Fortran are, of course, derived somewhat from the mathematical conventions of using i for the indices in series and n for the number of items in a set, both integers. So, in a rather roundabout way, i does indeed stand for "index."

Among a certain subset of people who learned BASIC in the late eighties, n is a popular loop index (followed by m and l.) Same reason.

k:

Yes that can include 'pointless' variable declarations and assignments rather than jamming nested function calls onto one line. The compiler will (more than likely) work it out to nice efficient code. Can also be a godsend for step-through debugging.

You have a point about debugging (fortunately, Java's hot code replace lets me change code and run it without having to restart the application), but I disagree strongly about the rest.

IMO assigning otherwise unused variables instead of chaining function calls generally is BAD for code readability and maintainability. The reason being that every variable adds state and thereby complexity. The fewer variables you need to implement the desired behaviour, the better. Heck, purely functional programming languages don't even HAVE variables!

dnm:

Single letter variables shouldn't be acceptable anyway -- even as temporary loop iterators. Its silly and ambiguous.

Your mom is silly and ambiguous.

And that should be "It's".

And single letter variables enhance clarity when used appropriately, as many programmers learn in their first week of programming class.

Strider:

As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I'm surprised no one has mentioned it yet, but it goes way back to FORTRAN on punchcards where i-n were automatically typed integers and therefore handy for for loops.

Strider:

As a side note, I don't know how many times i've switched up my i's and j's in nested loops and totally befuddled myself for hours...or minutes...they look so similar, who thought to use those two anyway?

I'm surprised no one has mentioned it yet, but it goes way back to FORTRAN on punchcards where i-n were automatically typed integers and therefore handy for for loops.

Back in the day, programmers used single-letter variable names and no whitespace, because Fortran IV statements had to fit into columns 7-72 of a punched card. Programming languages have advanced considerably since 1965, and it is much easier to use reasonably descriptive variable names in software.

By the way, use of one or two-letter variables beginning with i through n as loop indexes also comes from Fortran. In old-school Fortran, variables beginning with i to n were (by default) integer variables, and variables beginning with the other letters were floating-point variables.

stevekj:

Strider:

viola, problem solved, new coder learns.

How did violas get into this?

For some reason they seem to show up a lot more often than you'd expect for an otherwise underappreciated harmonic string instrument, and in the oddest places.

-- A viola player

At least he didn't say "walla."

-- A French speaker

I see nothing wrong with the original. Presumably at some stage the coder is going to use x and y for positioning.

This is standard mathematics that every 12 year old learns.

Somebody who doesn't intuitively understand what's going on there has no business writing code in the first place.

Using TT/LL/etc actually only serves to obfuscate what were originally very clear variable names.

Using the full names would only expose the rigid application of this standard in this case for the farce it is:

int Top, Left, Bottom, Right; // Top, Left, Bottom, Right