4

There are two hard things in computer science: cache invalidation, naming things, and off-by-one errors. - Tweeted by Jeff Atwood

Agreed. All software engineers can understand this. Choosing suitable names for variables can make an enormous difference in the readability of code. Very good programmers have an arsenal of both technical and descriptive words that they use to articulate complex tasks.

There's been times when I've thought for more than an hour on an appropriate variable name to give my code clarity.

It seems that to be truly effective at programming you also need to develop your vocabulary. However, I suspect there is a particular realm of words that are sufficiently descriptive, yet common enough that any reader can follow the flow of code.

So my question is how do I do this efficiently? I.e. not just reading lots of books. Perhaps there are courses that are oriented specifically for teaching useful coding vocabulary?

closed as primarily opinion-based by gnat, 17 of 26, user22815, Bart van Ingen Schenau, Thomas Owens Mar 31 '17 at 18:55

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 2
    thesaurus.com/browse/expand?s=t – jk. Mar 30 '17 at 15:25
  • 3
    An understanding of common design patterns will help, but a lot of the nomenclature comes from the domain you're working in. – jonrsharpe Mar 30 '17 at 15:33
  • You might want to re-think this approach: the code using an extended vocabulary may still be readable to those familiar with that extended vocabulary, but could be potentially unreadable or (worse!) misleading to developers familiar only with the commonly-used vocabulary. The result could actually be contrary to the expected one. – Dan Cornilescu Mar 30 '17 at 15:36
  • 2
    @DanCornilescu I'm specifically referring to a vocabulary that is easily understood. I don't mean the sort of language used in novels. – Klik Mar 30 '17 at 15:39
  • @Klik You're fine in that case. I thought it's important to mention it, tho. – Dan Cornilescu Mar 30 '17 at 15:44
5

As a simple rule of thumb that allows for easy understanding of what something is, and what it will do, I basically go with the following:

For a class:

Use a noun that describes what it is. E.g. Vehicle, Person, Building, Account.

For a method:

Use a verb-noun combination. E.g. FixBicycle, GetPayment, CheckTicket, ReadFile. Plurals used when parameter allows multiples to be passed in.

For a variable:

Use a noun that describes what it is holding: E.g. Teapot, Counter, Quote, Rectangle. Plurals used when it is an array or list etc.

Use namespaces:

This helps to make it clear regarding the context of the objects contained within.

So while you may have many 'MakePayment' methods in your app, one could be in MyApp.Customer.MakePayment, another could be MyApp.Bank.MakePayment, and also MyApp.Supplier.MakePayment.

If you are finding it hard to think of names because they may be three to six words long to describe what you are doing, there may be one of three things wrong:

  1. A class is too specific i.e. CustomerThatBuysMoreOnWeekends

  2. A method is performing too many things by itself - try to break it down to its component functions and name each as appropriate. Don't name the method by all the things it will do (such as PourTeaIfPotIsNotEmpty), name it by what the action is on a given object i.e. PourTea

  3. A variable that is too specific i.e. CustomersFilteredByCountry - just use Customers (that have been filtered)

4

I suspect there is a particular realm of words that are sufficiently descriptive, yet common enough that any reader can follow the flow of code.

That realm is the domain for which you are programming.

1

When facing specific naming challenges, I've found a thesaurus (online or paper) to be very helpful.

As for building up the skill:

Read lots of (high quality) programming books. The authors of these books will have put quite a bit of thought into the naming of variables and functions specifically to make the code as clear as possible.

More importantly, authors will generally have years of experience with the conventions common to the language or technology in question and will tend to use good idiomatic naming.

Of course, variables like foo and bar are very common (and for good reason!) when explaining syntax to separate developer-supplied names from language keywords. But most books will cover some meatier stuff by the end and will have realistic examples.

Also specifically read books like Code Complete, The Pragmatic Programmer, and other such books as they specifically address these issues of programming craft.

Reading lots of high-quality source code to see good examples is also a great idea, but now your task is even harder: finding high-quality source code!

I can't help adding: You might also be surprised how much great vocabulary for describing things you find in fiction - especially science fiction.

You say you don't want to just "read a lot of books", but that's my answer anyway. It's not going to get any easier than that. Any other method may be equally effective, but it will not be more efficient or as easy.

Edit:

After thinking about this some more, I should also add that this is one of those skills you gain by doing more than studying. Good naming is part of the programming practice itself.

Thinking really hard about your naming while you're doing it is building up that skill. Here are some things I personally try to concentrate on when naming:

  • What is the shortest unambiguous name for this thing?
  • Would namespacing allow me to have better local names?
  • Does this fit the problem domain itself or some technical aspect of the code? (Favor the problem domain for naming, if you can.)
  • Am I being redundant? (encode_function() vs encode())
  • Will this name make sense to me a year from now? (This question is hard.)
  • Does this cover the general case? (red_border vs border)
  • Is this too general? (stuff vs machine_state)
  • If I were describing this to a friend, is this the word I would use? If not, why not?

The list goes on.

It takes years and years to get really good at naming. You will cringe at 5 year old code. Then five years after that, you'll cringe again. Repeat.

Also, don't be afraid to rename stuff later. Most often, the "glaringly-obvious" correct name for a thing doesn't become glaringly-obvious until you've lived with it for a while!

  • 1
    Reading should be more than just programming books, variable naming is about communicating ideas of what your thinking reading books from other areas improves this ability. Also reading your own code six months later to see if you understand the variables can also help – user1605665 Mar 30 '17 at 22:29
  • @user1605665 Reading a widely pays dividends forever. I couldn't agree more. Likewise, the experience of reading your own code later is one that sticks with you - and it's an experience which would be hard to replicate any other way. +1 – DaveGauer Mar 30 '17 at 23:58
0

What works for me when I encounter a problem naming an identifier:

  • Describe the intended purpose of the identifier in several words, or even several sentences. This is important for me to fully understand its purpose. It may be embarrassing because it forces you to think. It's necessary though.
  • Iteratively reduce this description to its essence, checking that it remains reasonably descriptive and unambiguous.
  • To remove ambiguity or lack of clarity, rename identifiers in the code around if they interfere. (This step may invoke a recursive appication of the whole sequence.)
  • If needed, leave the longer description as a comment at the place of definition.

This process may make you rethink the structure and purpose of a function or a class you are naming, and end up as a refactoring in a cleaner way. This is usually a good thing if your code is not a quick one-time throwaway script.

0

A while back, I wrote an essay (for a blog that ended up never coming to be) in which I proposed three rules of naming, in order of precedence: keep them unique, keep them connotative, and keep them short. These rules were focused more on the name-meaning mapping than the rich-vocabulary issue, but I think they still apply here.

Unique means don't use the same variable to mean two different things. Sounds easy, but it's subtle. For one thing, it means avoiding using the same variable for multiple purposes within the same subroutine. I've seen code that reuses a string variable in two different aggregator loops in the same block - as if the programmer were trying to save those precious extra bytes. In a 4-G language. I'd avoid reusing a name even in the same file, mostly to avoid potential bugs.

Connotative means what you're getting at in the question - the name should remind the reader of the referent. It can pay to be precise here; if a variable denotes a file input stream of properties, I prefer propStream over propFile, and propInStream over that.

Short is self-explanatory. While modern IDEs cut down on the labor of typing long variable names, they still do nothing about the labor of reading them. Short names are least important, though, IMO, and uniqueness and meaningfulness should take precedence. But notice that I would prefer propInStream over propertyInStream. prop is (presumably) clear enough from context.

I consider a thesaurus to be of only limited value for naming. If I were using one, it would be to remind me of other common terms for what I'm trying to name. Meanwhile, I try to be generally well-read, so that I know what's in common use. I don't expect much use of referring to a linked list minus the head as the "thorax", for example.

  • DaveGauer's answer does remind me that a thesaurus may be handy, even critical, when naming a new class. If I connote badly, I mislead. – Paul Brinkley Mar 30 '17 at 16:37
0

Just like there are "domain specific languages", there are also "domain specific vocabularies", e.g., law, medicine, economics, etc, all have their own vocabularies. Rather than "expanding your vocabulary", per se, you want to expand your knowledge of the problem domain you're working in.

All programming involves some variables specific to the computer science domain, e.g., index, loop, list, array, etc. And, to be most easily readable, such programming-specific or housekeeping variables should be named as per that domain's conventions. And you presumably know all that already.

But any non-trivial programming quickly involves variables, data elements, etc specific to the problem domain at hand. And then your most-easily-readable variable naming will depend on that domain's nomenclature, conventions, etc. Besides programming knowledge, you always need a good understanding of the business (or whatever kind of profession) you're programming for. Good naming for your business-related variables would be just one more reason.

0

I like to use a translation tool like http://dict.leo.org . I am not a native english speaker (although quite fluent).

This does not only help in finding a suitable english translation, but often I use it forth and back to find similar, but different words until I found "the one".

Not the answer you're looking for? Browse other questions tagged or ask your own question.