This week's book giveaway is in the OCMJEA forum.
We're giving away four copies of OCM Java EE 6 Enterprise Architect Exam Guide and have Paul Allen & Joseph Bambara on-line!
See this thread for details.
The moose likes Cattle Drive and the fly likes Variable Naming Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of OCM Java EE 6 Enterprise Architect Exam Guide this week in the OCMJEA forum!
JavaRanch » Java Forums » This Site » Cattle Drive
Bookmark "Variable Naming" Watch "Variable Naming" New topic
Author

Variable Naming

Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
[John Abong]: I'm beginning to understand the role of variable/parameter naming as opposed to //commenting.

I'm moving this discussion out of the Assignment Log, since it is too interesting to hide away, and since I was tempted to hijack the thread

There was a point when variable names and method names started to gel for me... it's all very "it depends" and often enough I find that I'm not quite happy with what I come up with.

At one point I started seeing how the scope where a variable is declared can affect what sort of name I want to give it, and I have to decide exactly how much information it needs to convey - and what sort of information is useful in the context.

Sometimes number is a great variable name. It is exactly enough information. I have a number, and I am doing something with that number. At other times, number makes very little sense. What the heck am I using that number for? Is it height, weight, length, amount, count, a time lapse, an other measurement? Am I counting sheep? Do we care?

Method names is another really interesting one.

firstCountSheepThenSnore()

Too long? Too specific? Actually, I'd be tempted to say that my method is trying to do too much. Maybe I should have a countSheep method, as well as a snore() method. Or maybe the whole method should just be called takeNap().

countSheep( int sheep ) { ... }

Here I've got a pretty good method name, but it is a bit repetitive. I end up reading "count sheep sheep". Since the parameter is descriptive, it might be enough to just call the method count( int sheep )

study( String nameOfBookGivenToMeForMyBirthday )

So... will this method only work if the book was a gift, and more specifically, a birthday gift? Do we care that it was a gift?

My guess is that here study( String book ) is enough, but it will depend on the context.

How about listTableOfContents( Book title )? Probably good, but maybe listContents( Book title ) works better.

Kinda cool, to experience how variable names and method names affect how I read the code.
Marilyn de Queiroz
Sheriff

Joined: Jul 22, 2000
Posts: 9044
    
  10
What a great post, Katrina! Thanks for sharing.


JavaBeginnersFaq
"Yesterday is history, tomorrow is a mystery, and today is a gift; that's why they call it the present." Eleanor Roosevelt
John Abong
Ranch Hand

Joined: May 14, 2007
Posts: 79
I printed this one out... Thanks Katrina.
ahmed yehia
Ranch Hand

Joined: Apr 22, 2006
Posts: 424
Interesting! Thanks Katrina
Rory Lynch
Ranch Hand

Joined: Aug 03, 2007
Posts: 95
Very good.
Nice examples.

It reminds me of a nipick you directed at me on Java 4b Say



Hopefully I've taken it onboard


I wish that for just one time, you could stand inside my shoes.<br />You'd know what a drag it is to see you.
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
At work I see a lot of variable names that don't make much of an effort at telling their story. I recently had the pleasure of updating code with all of the following variables (and more)...



Then again, I look at stuff I did eighteen months ago and cringe... or ask who on earth wrote that ugly, monolithic thing and what on earth were they thinking, only to realize a few seconds later that that idiot must be me.

Pauline McNamara
Sheriff

Joined: Jan 19, 2001
Posts: 4012
    
    6
Great stories, Katrina, thanks for passing them on to us. And I like that nitpick a lot too, I'm taking notes...
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
My pleasure!

I'm a sucker for horror-code stories

Just today I was given a script to work with that had called three important variables <code>temp</code>, <code>test2</code>, and <code>test3</code>.

There was no <code>test1</code> or <code>test</code>, obviously.
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
I came across a great comment today, which sums up a grand portion of this discussion.

A good name is one that conveys a lot of correct information to the reader. A bad name conveys nothing, and a terrible name conveys <em>incorrect</em> information
<cite>Venkat Subramaniam / Andy Hunt</cite>

[ November 26, 2007: Message edited by: Katrina Owen ]
Dick Summerfield
Ranch Hand

Joined: Oct 04, 2007
Posts: 90
Originally posted by Pauline McNamara:
... And I like that nitpick a lot too, I'm taking notes...

Oh dear...

I shall try to stay optimistic and hope that in 18 months time I too shall be able look back and laugh.

In only the past month, though, I've been responsible for: num, temp, htu, and namePlusSpace just to name a few

Nice topic, Katrina. Thanks
[ November 26, 2007: Message edited by: Dick Summerfield ]
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
Originally posted by Dick Summerfield:

In only the past month, though, I've been responsible for: num, temp, htu, and namePlusSpace just to name a few


htu??? What on earth were you thinking? Seriously, though - I'm pretty sure we've all been there.

On one of my first assignments, I used <code>n</code> for the number. After a few years of mechanics and calculus, <code>n</code> seemed like the ultimate in obvious identifiers. Not so. I started realizing the value of convention. If you are working on a physics problem, <code>i</code> is most likely a vector. If you are taking calculus, <code>i</code> is an imaginary component of a complex number. And if you are writing a program in Java (or various other languages), <code>i</code> is most likely a looping index. (and if you are talking consumer hardware, it's probably something Mac related).

So just because it is short, doesn't mean it isn't really readable. I would much rather see
<code>for ( int i = 0; ...</code> than
<code>for ( int indexLoopingVariable = 0; ...</code>
Jinny Morris
Ranch Hand

Joined: Apr 29, 2007
Posts: 101
I once knew a programmer who named his variables a, aa, aaa, ... - when he ran out of a's (this was in the days when variable names had a short maximum length), he started in with b, bb, bbb, etc -
Pauline McNamara
Sheriff

Joined: Jan 19, 2001
Posts: 4012
    
    6
Originally posted by Jinny Morris:
I once knew a programmer who named his variables a, aa, aaa, ... - when he ran out of a's (this was in the days when variable names had a short maximum length), he started in with b, bb, bbb, etc -


I would love to hear someone talk through that code!
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
Originally posted by Pauline McNamara:


I would love to hear someone talk through that code!


No kidding! Reading it would probably make me speechless. How <em>do</em> you pronounce "bbb" (as opposed to "bb", of course)?
Dick Summerfield
Ranch Hand

Joined: Oct 04, 2007
Posts: 90
Perhaps I'm inserting a cat among the pigeons here but regarding variable names, I haven't always been too impressed by the choices in the instructors'solutions...

One example: "num" - it's fairly obvious what's meant, but why not make it "number" and be done with it (it appears the extra letters come free of charge ). "val" - same story - call it "value". But what about "tee" - Katrina would be happy that she could say it but what does it mean? Even after looking at the code I don't know.

To get back to John Abong's original point I'm really beginning to feel that readable code, not relying on comments, is A Good Thing, in fact an otherwise excellent example which I recently copied from the net was so full of comments that I made a copy of it with one comment at the top:
/* bulk of comments removed so we can see the code! */

...and it was a definite improvement, if only because it brought related code closer together.
[ December 05, 2007: Message edited by: Dick Summerfield ]
Pauline McNamara
Sheriff

Joined: Jan 19, 2001
Posts: 4012
    
    6
But what about "tee" - Katrina would be happy that she could say it but what does it mean? Even after looking at the code I don't know.

Ehm, lemme guess... was it in a program that had something to do with golf?

Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
I keep coming back to this.

Variable naming
Variable naming as opposed to commenting
The role of commenting

Oh, and the whole consistency thing.

I'm rereading Practices of an Agile Developer (Subramaniam/Hunt), and once again got to the chapter about Communicating in Code.

They mention (as a bad thing) comments that convey the obvious, such as
<code>//Constructor</code>
next to a class constructor.

Another great example of an unhelpful comment is
<code>
// this method allows you to passthrough
public void passthrough()
{
// code here
}
</code>

Their advice (which is the advice provided in many places, such as Martin Fowler's <em>Refactoring</em> book) is to rename the method and ditch the comment.

<code>
sendToHost()
</code>

Martin Fowler has a lot of great advice when it comes to writing readable code. He'll create a method for two lines of code if it allows him to eliminate a comment or otherwise increase clarity. The trick seems to be in the naming the method: name it for the intent of the code.
ankur rathi
Ranch Hand

Joined: Oct 11, 2004
Posts: 3830
Nice post. Enjoyed!

My idea is method name should give an idea what it does even if name gets longer. If you feel name is too long then your method probably doing many things...
Carol Murphy
village idiot
Bartender

Joined: Mar 15, 2001
Posts: 1195
Perhaps this explains my inability to decipher code that has foo and bar for variable and/or method names. Obviously, if it's foobar, then it won't work and why are we bothering?
The use of these particular names make practice certification tests impossible for me to do. I end up with foobar rattling around in my head like a dried up pea in an empty aluminum can.
I love your input Katrina!
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1358
    
  17
Originally posted by Carol Murphy:
Obviously, if it's foobar, then it won't work and why are we bothering?




My worst ever experience - even worse than frankencode - was my last Java exam in college. All the programs were written in Norwegian. They provided me with translations of all the identifiers into English on a separate piece of paper.

I just couldn't get the meaning of the programs! I spent nearly half the allotted time <del>wishing the professors would wake up with hideous boils all over their bodies</del> trying to decipher and find the flow of the programs. It literally felt like my brain was writhing and twitching.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Variable Naming