Abbreviations vs full words in variable names


#1

Totally agree! I do the same because I DO want my variables to look like variables, and DO NOT want them to look like method calls.

On the contrary, my experience is that variables should look like variables. Although very experienced in programming many languages, when I first saw the SketchUp Ruby API documentation’s examples, they made no sense, because I COULD NOT tell what was a variable and what wasn’t.

The “mix-up” happens in the human mind reading the code. (As your comments on trying to read code being a mixture of English and French attest.)

Not perhaps with the Ruby interpreter which (I think always checks against the list of variables and methods in the current scope, whilst parsing.) See:

Programming Ruby: The Pragmatic Programmer’s Guide
Davide Thomas and Andrew Hunt

Part III. Ruby Crystallized

Variable / Method Ambiguity

When Ruby sees a name such as “a” in an expression, it needs to determine if it is a local variable reference or a call to a method with no parameters. To decide which is the case, Ruby uses a heuristic. As Ruby reads a source file, it keeps track of symbols that have been assigned to. It assumes that these symbols are variables. When it subsequently comes across a symbol that might be either a variable or a method call, it checks to see if it has seen a prior assignment to that symbol. If so, it treats the symbol as a variable; otherwise it treats it as a method call. As a somewhat pathological case of this, consider the following code fragment, submitted by Clemens Hintze.

def a
 print "Function 'a' called\n"
 99
end

for i in 1..2
 if i == 2
   print "a=", a, "\n"
 else
   a = 1
   print "a=", a, "\n"
 end
end

produces:

a=1
Function 'a' called
a=99

During the parse, Ruby sees the use of “a” in the first print statement and, as it hasn’t yet seen any assignment to “a,” assumes that it is a method call. By the time it gets to the second print statement, though, it has seen an assignment, and so treats “a” as a variable.

Note that the assignment does not have to be executed—Ruby just has to have seen it.

I never “bare call” any method however. I will always add empty parenthesis to “help” Ruby understand that it’s a method call and not a variable reference.
So in the code example, I’d have used:

 if i == 2
   print "a=", a(), "\n"

… to help both Ruby and human readers know immediately the reference was a method call.


Delete duplicate string characters in a array
#2

What looks like a variable differs between languages. In PHP variables look @like_this. In Ruby variables and method calls do look the same. Just as you can name a variable mod you can name a method mod. I don’t see how using abbreviations help you distinguish variables from method calls, unless you apply styling conventions from different languages. There is probably such a convention in other languages you use but there is no such rule for Ruby.

In better organized code bases it’s quite easy to distinguish them though as methods are usually called on an object, e.g. a module. Sketchup.active_model is a method while active_model is typically a variable. The only place where active_model in itself is a method is when you are defining code inside of the Sketchup module (or any other module/class that has a method by that name). As each class and module should ideally have a very limited number of methods it’s quite easy to remember them all. Also each method should ideally only be 10 lines long, meaning it’s easy to see what has been assigned to a variable already.

If empty parenthesis or naming conventions are required to differentiate method calls from variables I think the code needs to be better organized.

Anyhow, this starts to get off topic. If the discussion on abbreviations vs full words continues I think it needs a separate thread.


#3
Eneroth3's rules for variable naming, ... (continued) ...

Only in YOUR code. This is subjective opinion.

You miss the whole point. I WOULD NOT !

Again, subjective. You don’t need to “see”. I don’t code to please you specifically nor anyone else’s subjective coding style.

Nor should every coder be told they must use “verbose” variable names that comply with Eneroth’s subjective personal styling.

You seem to have “latched onto” the reason of “variable / method call ambiguity” which is only part of my variable naming preference.

The more important thing for me (subjectively) is that variables look immediately like variables have looked in every other coding language I’ve used over the past 35 years (or so).
This includes what variables look like in every one of my college programming textbooks, in every example in every programmer’s reference I’ve read, etc.

Regarding, Ruby specifically, *I* have 4 editions of Thomas’ and Hunt’s old “Pick-Axe” textbook. It is chock full of code examples with variables that are abbrevs, like val instead of “value”

I my mind, theres is no question that in …

mod = Sketchup::active_model
matls = mod.materials

mod is a reference to a Sketchup::Model instance object, and that matls is a reference to it’s Sketchup::Materials collection of Sketchup::Material instance objects.

BUT, I do not purposefully abbreviate just for the sake of abbreviating. I will often find myself typing something like this:

model = Sketchup::active_model
matls = model.materials

Ie, the name model is short enough. But like Andreas showed in his example above, I often use very descriptive method parameter names especially if the method will be used by someone else.

This would be “cryptic” for a library method …

def remat(ents, mcache={}, visdefs=[])

… but not for a private method only used internally and not called from outside the module / class.

[quote=“eneroth3, post:15, topic:58376”]
… unless you apply styling conventions from different languages. [/quote]

Mere speculation. I don’t need to for Ruby.

Have used.

There are some that promote “type styling”. Usually Microsoft Visual languages that have strongly typed variable references that cannot be made to point at objects of other types. They promote prefixing with lower case letters indicating type such as sName for a string variable, `iCounter for integer, etc.

This has no place in Ruby as it only has references that can variably point at any kind of object, at any time.

I (and the text from the book,) did not say required, … I said simply I personally prefer to help speed up Ruby’s parser.

The simple solution of course is to do what @dynamiqueagencement, others and I do, … that is to not name variables that “read” to the human like method names.

@dynamiqueagencement, there is nothing at all wrong with your variables names if this code is only going to be read and maintained by you. Go on ahead and keep using them as is.
HOWEVER, if you will post snippets, you should at the least tell the readers what the variables reference. If you put comments right in the code this might be best.

You can run the risk that some

Not fair to “ding” me and then shut down the talk.
Your fault for starting this in this thread instead of in a new “linked” thread.
(Perhaps get Aaron to prune it off to a new thread?)


#4

I realized as I was writing that we were getting of topic. Anyhow, I made a new thread now.

But there is no convention for Ruby how a method name vs a variable name looks. Very often there are even pairs of variables and methods by the same name when using getter and setter methods. I don’t even know what you mean by “mod” reading like variable and “model” reading like a method. Any of them could be both. Is there a C convention about abbreviating variables, but not method names?

This is of course subjective and anyone can invent there own style but I find extreme and unpronounceable abbreviations to be quite unconventional in a Ruby context. The exception to extreme abbreviations is when the variable is immediately referenced and then never again, e.g. my_array.each { |e| do_something(e) }, but when a variable is referenced 5 or 10 lines later this doesn’t rad well.

This shouldn’t be much of a problem though as a method should ideally be no longer than 10 lines.


#5

Thanks, this is an interesting topic for us “code geeks”. :nerd_face:

Don’t know, as I try to avoid C myself. But as I remember there are those sources that promote the type prefixing of variable names. Yes, they do tend to be very terse. But this doesn’t matter much to Ruby. (You can see many of Ruby’s underlying C code in the official Ruby docs. Each method has a “click to toggle source” link that appears when your mouse is hovering over the method documentation.)

As an example, this is the C source for Ruby’s File#owned?

static VALUE
rb_file_owned_p(VALUE obj, VALUE fname)
{
    struct stat st;

    if (rb_stat(fname, &st) < 0) return Qfalse;
    if (st.st_uid == geteuid()) return Qtrue;
    return Qfalse;
}

Well, I suppose then it is what a person has become accustomed to. If they first read the very “wordy” examples in the SketchUp API, then they’d think that was the “convention”.

Exactly! It is subjective. I just do not agree with forcing a “new coder” to abide by a subjective style rule “strongly promoted” in an informal learning (forum) situation, … whilst formal learning situations (books or classes,) are discouraged (slapped down) each time I suggest it.

The basic problems these “new coders” are having stem from an absolute lack of the basic programming concepts, common to any programming language. Namespacing, loop constructs, indentation, recursion, etc.
It would not take that much time to read an Ebook on basic programming concepts.

Anyway, … I am not against asking coders who post “help me” code, to explain whats happening and what is intended, and making the code readable (correct indentation, etc.)
I am against enforcing subjective personal preferences upon everyone.

I know this is not something I follow nor see anyone else following, even in the Ruby Standard Library.


Don’t get me wrong. I am not for obfuscating code just to make it hard to read.

I DO go above and beyond to make my code understandable if it’s a library that others will use.
BUT I do not go to verbosity extremes with variable names. Never will.

I looked through “Ruby Best Practices” and even searched for “naming” and found nothing regarding verbose variable names.

Gregory Brown does say in Conclusions, p297 …

When it comes to design, much can be gained by simply reducing complexity. If the
path you’re on seems too difficult, odds are that it can be made a lot easier if you just
think about it in a different way. As for “clever” implementation tricks and shortcuts,
they can be more trouble than they’re worth if they come at the expense of clarity or
maintainability of your code.

Put simply, the worst practices in Ruby are ones that make you work much harder than
you have to.

He did not expand or describe “clarity” anywhere in the preceding book, but as he said on pg xxi

This book isn’t really written with the Ruby beginner in mind, and certainly won’t be
very useful to someone brand new to programming.

… he began that Preface with the following, pg xi

Some programming languages excel at turning coders into clockwork oranges. By
enforcing rigid rules about how software must be structured and implemented, it is
possible to prevent a developer from doing anything dangerous. However, this comes
at a high cost, stifling the essential creativity and passion that separates the masterful
coder from the mediocre. Thankfully, Ruby is about as far from this bleak reality as
you can possibly imagine.

As a language, Ruby is designed to allow developers to express themselves freely. It is
meant to operate at the programmer’s level, shifting the focus away from the machine
and toward the problem at hand. However, Ruby is highly malleable, and is nothing
more than putty in the hands of the developer. With a rigid mindset that tends to
overcomplicate things, you will produce complex Ruby code. With a light and unencumbered
outlook, you will produce simple and beautiful programs. In this book, you’ll
be able to clearly see the difference between the two, and find a clear path laid out for
you if you choose to seek the latter.

A dynamic, expressive, and open language does not fit well into strict patterns of proper
and improper use.


#6

I always use parenthesis to distinguish between variables and methods. Also use C like syntax when ever possible since I have a very strong background in C / C++.

I generally declare local variables up front and initialize them.

If a global variable is useful then I generally put them into a structure and pass the structure into the method. So then you access them using dot notation.

In some cases 10 lines in too many for a method and in some cases not enough. So there isn’t a hard rule here. If you have 8 lines and you are coupling more than 1 idea within the method then maybe it could be broken down. On the other hand I have case statements that can easily be 20, 30 or even 40 lines long (1 line per case where I am assigning a structure element from a file read.

In the end - stylistic issues are personal (or company set) and should be chosen for readability, maintainability and scaling.

Of course this is just an opinion of someone who started coding in the late 70’s.


#7

IMHO. The more a variable or method describes itself, the better the code is readable by other coders, or by the original coder over time.

I prefer

active_model = Sketchup.active_model()
entities = active_model.entities()

over

m = Sketchup.active_model
e = m.entities

Do I always do what I prefer? No.


#8

Single letter is a bit too concise, except for iterator / index vars.

I usually tend to prefer (in my own code) short 4 or 5 character reference names. (It’s not a hard set rule.)

If in a loop / Ruby iterator, if it is not an integer index, but some other object type, I like to use some thing more descriptive, such as inst for component instances, grp for group instances, or str or path for strings, etc.

For example I often use well known abbreviations for points like: pt or pt1, pt2 , etc. …
The name model is short enough (but I’ve been known to use mod or modl on occasion.)

I often prefer ents or sometimes I’ll prefix it as ments for model entities, gents for group entities if I have both referenced in the same scope.

But this is my own code. I am tending to be more descriptive if it’s a public example, or a template or a library meant for others to use.


#9

I prefer single character variables for loops that run of one line, e.g. array.map { |e| e*2 }. I avoid names like ments and gents that are hard to pronounce, especially if they easily read as a different word the way gents does (short for gentlemen and commonly used for bathrooms) but used to use them a lot.

If there for instance are several entities collections in the same Ruby scope, I’ve lately stopped having variables for them. Instead of gents I would typically write group.entities, where group is the reference to the parent group, even if that mean I have to repeatedly call the entities method. When going back to older code I’ve found this to be easier to read.


#10

This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.