From: Daniel Finnie <danfinnie@...>
Date: 2007-02-22T14:32:26+09:00
Subject: Trade-off between variable name descriptiveness and readability

As a mentor of the new adopt-a-newbie system, which I think is going 
excellently, I was reviewing a 99-bottles-of-beer method.  We went over 
what he had, what I thought could be better and I showed an example of 
exactly how I would do it, which was this:

 > def sing_song(start)
 > 	start.downto(1) do |numBottles|
 > 		puts "#{numBottles.bottles} of beer on the wall, 
#{numBottles.bottles} of beer!"
 > 		puts "Take one down, pass it around, #{(numBottles-1).bottles} of 
beer on the wall"
 > 		puts
 > 	end
 > end

String#bottles just does "x bottle(s if needed)."  Anyway, one could 
further refine this code to be more english-y by changing numBottles to 
num in the following way:

 > def sing_song(start)
 > 	start.downto(1) do |num|
 > 		puts "#{num.bottles} of beer on the wall, #{num.bottles} of beer!"
 > 		puts "Take one down, pass it around, #{(num-1).bottles} of beer on 
the wall"
 > 		puts
 > 	end
 > end

I doing this, the code reads better but the variable's name loses a lot 
of its descriptiveness.  What would all of you guys do?  I was also 
thinking of renaming the bottles method to disp, but that has the 
potential to conflict with a lot of other things and doesn't really 
describe what the method does.  I also considered putting 
numBottles.bottles into a variable but it didn't seem right.

Dan