How "self-documenting" can code be without being annoying?

Question

I am not sure what the best practices are here, but I often see abbreviated variable names especially when the scope is small. So (to use simple Ruby examples) instead of def add_location(name, coordinates), I see things like def add_loc(name, coord)—and I might even see something like def add_loc(n, x, y). I imagine that longer names might tire a person out whose used to seeing abbreviations.

Does verbosity help readability, or does it just hurt everyone's eyes?—Do people prefer abbreviations and shortened names over longer names?

Answer 1

Personally, I would MUCH rather see longer names that actually mean something without having to determine the context first. Of course, variables that don't lend real meaning, such as counters, I still use small meaningless variable names (such as i or x), but otherwise verbosity is clarity most of the time. This is especially true with public APIs.

This can be taken too far, however. I've seen some VB code in the past that way ridiculous. Moderation like everything else!

Answer 2

Never abbr.

Answer 3

The only time I accept abbreviations is for local variables that are only in scope for a small period of time.

Meaning they should be coming into scope with a very readable method or constructor.

Answer 4

I actually use long variable names all the time, after all modern IDEs and texteditors have completion, so there is nothing wrong with using index instead if i. The only exception I have is when dealing with coordinates b/c x and y make the most sense there.

Answer 5

Longer names are much better. You mention that you often see abbreviated names in small scopes. Who's to say the scope will remain small as the software grows?

Of course, XCoordinateForCurrentLocationOfSelf is a ridiculous name, so just be reasonable. Especially if you're walking into a project you've not worked on before, you'll thank anyone who used descriptive function and variable names.

Answer 6

When programming you are using the syntax so that humans can read it, the length of the variable names, methods, etc... are really irrevelant.

The more verbose the better usually, with a good development environment you should have code completion anyway, so you can simply hit "add_L"+TAB to finish the method call.

Answer 7

Personally, I find verbosity a good thing, but it's easy to be overly verbose too, which is a bad thing. There is a balance, and abbreviations can come into that balance too.

These are my general rules:

• Iterators can be one letter, ie. i, j, k, etc.
• Other one word variables like boolean toggles, what have you are never abbreviated, ie. installing, done, etc.
• Multiple word variables and function names are candidates for abbreviation, but only if they are starting to get rediculously long (say, 20-25+ characters). Intelligent abbreviation is the key here. function => func for instance, but never fun, f, or functi

Answer 8

I agree with Kilhoffer; I prefer to see descriptive variable names in almost every context. I will abbreviate if my variable names are longer than 20 characters or so, usually with words in the variable name (eg: "SomeVeryLongVarValue").

Of course, I also use hungarian notation whenever I can, so I might well be in the other extreme camp of trying to make my variables names overly descriptive, depending on your perspective.

Answer 9

Try to read your own code 1 yr later. You'll see both the value of self documenting variable names, and the value of the code comments ( and specially the value of clean code )

When you grab someone else source code and you don't understand it it's easy to think "Well he is not as good programer as I am" But when you realize that your own code is hard to read you go like: "what was I thinkng?"

In the long run verbosity helps maintainability. For short one line script, you can still use "setLocNm" instead of setLocationName"

Any fool can write code that a computer can understand. Good programmers write code that humans can understand. -Martin Fowler

Answer 10

I think that the main problem with abbreviations is that not all the people abbreviates on the same way, so when you work with many people it only can increase the probability of error when coding. For example if you have a constant that can be called SOMETHING_INTERFACE, maybe some developers would abbreviate it as SOMETHING_INTFACE, others as SOMETHING_IFACE or SOMETHING_IF, SMTHING_IFACE...

With only two words you can have at least half a dozen of more or less "logic" possible abbreviations, so I think it's better in the most of the cases to write without abbreviations and with more reasons if you want to have self-docummented code.

Very long names can be annoying sometimes, but can also be abbreviated in very local scopes using auxiliar variables.

Answer 11

I think it's ok to abbreviate when the name would hurt readability or just be redundant.

Example 1: An argument to a method where the type allready conveys all information necessary.

Example 2: A variable that will be use a lot in an obvious way

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

Example 3: Idiomatic abbrevations. i,j,k has allready been mentioned. "sb" above is one in our code, and each team probably has a couple more.

Answer 12

Out of scope things like constants and globals should have long descriptive names. Sometimes a really long name will make it "smell" just enough to signal it's presence as being unwanted. This is a good thing becuase it will 1 - make people avoid it, 2 - increase the pressue to refactor the code to make it go away.

Answer 13

A variable should be given the shortest possible name that adequately conveys its purpose.

Over-verbosity tends to conceal syntax, and syntax is important.

Across a whole program (or application/system) variables should be named with consistent style and similar things should be named similarly. If a convention exists within the language community, it should be observed (so don't camelCaseRubyVariableNames) unless there is some compelling reason not to do so.

Abbreviations, if used, should be consistently applied everywhere and if domain-specific, should be recorded somewhere. If someone is going to spend any useful amount of time with the code then they'll soon learn.

If you need to combine as many as five or six words to name a variable then I'd suggest you might be looking at a code smell and the routine you're working may benefit from a little work.

Mostly, though, if you're aware of the pitfalls and actually think about what you're writing, the chances are that your code will be reasonable. Imagine yourself describing the function you're working on to a new colleague - the less you think you'd need to say, the better the code probably is.

Answer 14

I am probably going to be completely booed but I wanted to make sure this view was heard.

While longer variable names can be more descriptive they can begin to mire the original intent of the program. I feel that on API elements it is important to have clear and meaningful names in the context that they will be used.

Within each function or method this is often a different story. I try to write less and keep it very terse. This is known as spartan programming al a Mr. Atwood and this nifty example. Yes, the example is clearly rigged but it does demonstrate how having a little less ceremony can actually make reading the program easier.

Good luck.

Answer 15

Aim for shorter rather than longer, but reader understanding should trump laziness to type every single time.

As others have said, variable name length shouldn't obscure logic or algorithm. For example, in arithmetic, we write

( 1 + 5 ) * 3 = 18

rather than

three multiplied by the sum of one and five equals eighteen

because we are trying to draw attention to other things than the clarity of the elements involved in the expression.

I tend to keep variables to one to three words, abbreviating only when I exceed 24 characters or so. The less frequently a variable is used, the more likely I am to feel free to make the variable name long. More frequently used variables I will make shorter.

Answer 16

There's a good related question about this. In particular, check out amdfan's response.

Answer 17

I browsed through the answers, but I don't see if the following is covered. Here it goes...

Whether you abbreviate or being verbose, just ensure that you have used no more words than necessary and the meaning is damn obvious.

But even after this filtering if your identifiers look verbose, you have a flaw in your design.

def initialize_report_template()
end

should have been...

class ReportTemplate
    def initialize()
    end
end

Answer 18

Most people sight read, It takes no longer to read a word then to read an individual letter. So always use meaningful names. Do they have to be complete 7 word descriptions, no but they need to be longer enough to understand.

I could accept add_loc(name, coord), as they are long enough I can tell what they are. In add_loc(n, x, y), I would object to 'n' instead of name. I could live with X and Y as these are the accepted names of coordinates.

For someone not familiar with coordinate systems I could see where add_location(name, coordinates) would be more meaningful.

When in doubt, use longer names.

Answer 19

I suggest taking a minimalist approach. Use a little as possible while ensuring your code stays clear, concise and to the point.

Answer 20

"It's OK to figure out murder mysteries, but you shouldn't need to figure out code. You should be able to read it." -- Steve C. McConnell

That said, if you think that you nor anyone else needs overly explicit variable names and so on, feel free to shorten them.