• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Variable Naming

 
Katrina Owen
Sheriff
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
[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
Posts: 9068
12
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
What a great post, Katrina! Thanks for sharing.
 
John Abong
Ranch Hand
Posts: 79
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I printed this one out... Thanks Katrina.
 
ahmed yehia
Ranch Hand
Posts: 424
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Interesting! Thanks Katrina
 
Rory Lynch
Ranch Hand
Posts: 95
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Very good.
Nice examples.

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



Hopefully I've taken it onboard
 
Katrina Owen
Sheriff
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 4012
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 103
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 4012
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 90
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 4012
6
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 3830
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1203
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic