Wednesday, July 8, 2009

The U Controversy

It is a tempest in a teakettle, to be sure, but among the points of friction and discovery today was one about the use of the letter 'u' as a variable name. The case in point was a nice, small function, not much larger or more complex than this stupid example:
      public void Whatever() {
            User u = new User();
            if (u.hasSomeAttribute()) {
               u.setSomeValue();
           }
      }

The focal point is the letter U as a variable name. Because of my involvement in a particular book project, I was summoned into the conversation and carried half of it for some time.

I would rather see "user" than "u" because of my rules about pronounceable, grep-able names that don't require any mental mapping. That is my preference. Therefore, I can clearly NOT choose the variable name "u."

I also have publicly stood by James Grenning's assertion that the length of a name should have some correlation with its scope. A name that serves as a loop counter is inappropriate as a parameter name, function name, property name, class name, or module name. In that case, the variable clearly should not have been named "user."

Now, the team has chosen fully-spelled English word names, so I can clearly not choose to name the variable "u", however, there is no additional content or usage exposed by using the longer name so I can clearly not choose to name the variable "user."

The name 'u' does not actually violate the "pronounceable names" rule since it can be pronounced "ewww", so I can clearly not choose to call it "user". Yet if I pronounce it as spelled, it is "uh" which makes me sound like an idiot so I can clearly choose not to call it "u."

The programmer in question is a bright, well-educated, professional man with a strong mathematical and scientific background, well accustomed to effortlessly dealing with single-letter variables in larger and more complex contexts, so he may (without harm) clearly choose not to call the variable "user."

The past misuse of short and cryptic variable names have left a very foul taste in the mouths of our programmers, who have spent many hours trying to figure out what xtmp and z and t and c stand for when they are stumbled upon in the bowels of some deep function, so to distance ourselves from the perpetrators of these bad names we can clearly choose not to call the variable "u."

Ultimately, the conversation needed to fall upon two relevant points. One is that the name 'u' is perfectly acceptable in the limited context in which it appears, and the other is that the team has chosen to use fully-spelled English names.

That set of facts would leave us with a single, clear path. The variable should be named 'user' in compliance with the desires of the team, with the option of revisiting the rules to allow shorter names in limited context at the next retrospective. But along the way, the programmer should also be given some validation that the name is really not problematic in this context in any other way.

Programming in its current agile form is as much a social discipline as a technical discipline. While there is no reason to surrender one's mind and taste at the door it is reasonable that we recognize the will of the team and try to work within its boundaries.

I am not condoning an oppressive environment or coercive control through peer pressure, but rather that we join a team on its terms. When I have come to a team on my own terms, I have not been as valuable a member as I intended to be. I have learned that it makes good business sense to choose one's battles instead of fighting them all, and if possible to win our battles through technical merit instead of force of will. A reasonable amount of sensitivity goes a long way.

10 comments:

  1. Seems this could go either way in the context of this post and the code is easily readable and clean as is....but

    One other reason I would personally refactor the variable to "user", even if I was the original coder of "u" myself, is to practice being consistent with team standards and to get myself into the habit of using the team standards and conventions .... even in this small of a piece of code.

    I find that I will take short cuts in other places of the code if I allow myself the luxury of taking short cuts in small, simple pieces of code.

    This is a nice subject since it is probably a pretty common debate within most teams at one time or another.

    Thanks
    Dr. Bubba

    ReplyDelete
  2. I realize this post isn't so much about the convention, but...

    "the name 'u' is perfectly acceptable in the limited context in which it appears"

    Acceptable, sure, but ideal, no. The extra microseconds that the brain needs to process the "u" add up--maybe not to any real significant time, but the net effect of lots and lots of such encodings adds up in other ways. It's like riding a car--eventually the noise of being on the road, even though it's not very noticeable, wears you down (try wearing earplugs next time you take a long trip and you'll feel the difference).

    With a good IDE, it costs almost nothing extra to use "user." And it can be paraphrased (read out loud) a lot more easily. While in general the rule about scope and variable names is ok, I don't think it prohibits things like "user" as a local variable.

    Also, if you use a language that doesn't require type declaration, you really don't want to be using variable names like "u."

    ReplyDelete
  3. Exactly how long did you spend arguing over three letters, and how much did that cost in man-hours?

    I understand the need for rules and consensus, but...

    ReplyDelete
  4. Mis used variable names are one of the commonest forms of slopppy coding I always see, they make code so hard to understand ,but with a little discipline they are so easy to correct

    the conversation is well worth the time

    Jeff Anderson
    agileconsulting.blogspot.com

    ReplyDelete
  5. Sorry if I upset anyone.

    I guess after seven years of dealing with Ramanji variable and function names, the idea of forming an ad-hock committee to interrogate someone over a variable name struck me as arrogant and rude to the point of intolerance.

    I guess I have become acclimated to a different world.

    ReplyDelete
  6. Wally,

    A little context:

    This was a pairing session, not a post-facto inspection, and the people involved were sitting within arms length of each other. The only reason I was even aware of it was that I was the next seat over, and wrote the naming chapter in Clean Code. No committee was formed.

    Also, the point wasn't that the guy is a jerk or anything. It's just that the name wasn't a horrible travesty, but that clean naming is one of the ways the group has decided to work.

    Certainly, we've seen much worse. It was mnemonic and the scope was very short. Heck, I'm tickled he wrote such a short function.

    Small things are a small matter, but I'm glad the team has certain standards they've agreed upon and that pairing gives them the continuous inspection benefit.

    The argument didn't matter. The variable name only mattered a little. It was all in the human dynamics.

    Tim

    ReplyDelete
  7. :)

    Tim, it is quite interesting to read how you saw it.

    I enjoyed comments much. Truly you are preaching to the choir. None of commenter gave a though to the origin of the situation. Why? Preciously few of commenters question why the full word is better. (And I still doubt it. This is another story, but it “is not more wondrous than the story” about why introspection fell off favor among professionals.)

    You thoroughly provoke me to start my own blog. I think I will.

    ReplyDelete
  8. Vadim:

    I think you're a capable and fascinating coworker. If you write a blog, I will definitely subscribe to your postings via VSS.

    I would also recommend Vadim to all who follow my blog. Wally in particular would enjoy reading him.

    As with other capable thinkers, we won't always agree, but I value Vadim's mode of thinking and his sense of humor very highly.

    tim

    ReplyDelete
  9. I'm glad vadim piped up.

    I like single letters sometimes. I like single letters for indexes, and I like them for one liners. When I'm doing arithmetic or some other math, sometimes single letters can actually represent the domain better.

    If we could make a rhyme of when it's appropriate to use single letters, we could end it with Sam I am and start a new meme. But what rhymes with generator expression anyway?

    I'm discovering that sometimes you can avoid the variable altogether. Most of the time when programming for my ham I'm in a situation where I just can't do that very often.

    (Java, Ruby, and Python don't lend themselves to function composition. I've found that Factor is pretty cool for that though.)

    ReplyDelete
  10. I was impressed with the rule that the length of a name and the scope of the name should vary directly. A very tiny scope (generator expression, lambda) can tolerate a very small variable name. A local variable, a little longer. A method name or parameter name is visible to more people and needs to be more descriptive.

    The other side of this is the cumulative context idea. You have the application, then the module, then the namespace, then the class, then the method, then the variable. If Accounting.GeneralLedger.TeeAccount.Debit(amount) is good enough, "amount" doesn't need a longer name. This also suggests that the deeper a name goes, the less it has to explain.

    Those having been said, I still like whole words better than abbreviations.

    While you're here, check out the card about Vadim's rules for abbreviations at AgileInAFlash.com.

    ReplyDelete