How “self-documenting” can code be without being a

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 2 years ago.

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 when they're accustomed 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

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 2

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 3

Max Kanat-Alexander, the chief architect of Bugzilla, says this on his blog:

Code itself should take up space in proportion to how much meaning it has.

Basically, tiny symbols that mean a lot make code hard to read. Very long names that don’t mean much also make code hard to read. The amount of meaning and the space taken up should be closely related to each other.

http://www.codesimplicity.com/post/readability-and-naming-things/

It's a very insightful post about naming things. I urge everyone to read it!

Answer 4

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 5

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 6

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