Better identifier names?

Question

How can I train myself to give better variable and function names (any user-defined name in a program).

Answer 1

Practice.

Always be thinking about it whenever you write or read code, including other people's code. Try to figure out what you would do differently in their code and talk to them about it, when possible (but don't harp on it, that would be a nuisance). Ask them questions about why they picked a certain name.

See how well your code reads without comments. If you ever need to comment on the basic purpose of something you named, consider whether it could have a better name.

The biggest thing is active mental participation: practice.

Answer 2

This is a subjective question.

I strive to make my code align with the libraries (or, at the least the standard ones) so that the code has an uniformity. I'd suggest: See how the standard library functions are named. Look for patterns. Learn what different naming conventions exist. See which one makes the most sense. E.g: most Java code uses really big identifier names, Camel casing etc. C uses terse/short names. There is then the Hungarian notation -- which was worth the trouble when editors weren't smart enough to provide you with type information. Nowadays, you probably don't need it.

Answer 3

Joel Spolsky wrote a helpful article on Hungarian notation a few years back. His key insight is this:

Let’s try to come up with a coding convention that will ensure that if you ever make this mistake, the code will just look wrong. If wrong code, at least, looks wrong, then it has a fighting chance of getting caught by someone working on that code or reviewing that code.

He goes on to show how naming variables in a rigourous fashion can improve our code. The point being, that avoiding bugs has a quicker and more obvious ROI than making our code more "maintainable".

Answer 4

Read some good code and imitate it. That's the universal way of learning anything; just replace "read" and "code" with appropriate words.

Answer 5

Thinking of names seems to be something that some people are extraordinarily bad at, and I'm not sure what the cure is. Back when I was an instructor working in commercial training, I'd often see situations like this:

Me: OK, now you need to create an integer variable to contain the value returned by getchar().

[Trainees start typing, and I wander round the training room. Most are doing fine, but one is sitting like a deer frozen the headlights]

Me: What's the problem?

Him: I can't think of a name for the variable!

So, I'd give them a name for it, but I have a feeling that people with this problem are not going to go far in programming. Or perhaps the problem is they go too far...

Answer 6

A good way to find expressive names is starting with a textual description what your piece of software actually does. Good candidates for function (method) names are verbs, for classes nouns. If you do design first, one method is textual analysis.

Answer 7

• (Even if you are only a team of 1) agree a coding standard with your colleagues so you all use the same conventions for naming. (e.g. It is common to use properties for values that are returned quickly, but a GetXXX or CalculateXXX method for values that will take time to calculate. This convention gives the caller a much better idea about whether they need to cache the results etc). Try to use the same names for equivalent concepts (e.g. Don't mix Array.Count and List.Length as Microsoft did in .net!)

• Try to read your code as if somebody else wrote it (i.e. forget everything you know and just read it). Does it make sense? Does it explain everything they need to know to understand it? (Probably not, because we all forget to describe the stuff we "know" or which is "obvious". Go back and clarify the naming and documentation so that someone else can pick up your code file and easily understand it)

• Keep names short but descriptive. There is no point writing a whole sentence, but with auto-completion in most IDEs, there is also little point in abbreviating anything unless it's a very standard abbreviation.

• Don't waste characters telling somebody that this string is a string (the common interpretation of hungarian notation). Use names that describe what something does, and how it is used. e.g. I use prefixes to indicate the usage (m=member, i=iterator/index, p=pointer, v=volatile, s=static, etc). This is important information when accessing the variable so it's a useful addition to the name. It also allows you to copy a line of code into an email and the receiver can understand exactly what all the variables are meant to do - the difference in usage between a static volatile and a parameter is usually very important.

• Describe the contents of a variable or the purpose of a method in its name, avoiding technical terms unless you know that all the readers of your code will know what those terms mean. Use the simplest description you can think of - complex words and technical terms sound intelligent and impressive, but are much more open to misinterpretation (e.g. off the top of my head: Collation or SortOrder, Serialise or Save - though these are well known words in programming so are not very good cases).

• Avoid vague and near-meaningless terms like "value", "type". This is especially true of base class properties, because you end up with a "Type" in a derived class and you have no idea what kind if type it is. Use "JoystickType" or "VehicleType" and the meaning is immediately much clearer.

• If you use a value with units, tell people what they are in the name (angleDegrees rather than angle). This simple trick will stop your spacecraft smashing into Mars.

• For C#, C++, C in Visual Studio, try using AtomineerUtils to add documentation comments to methods, classes etc. This tool derives automatic documentation from your names, so the better your names are, the better the documentation is and the less effort you need to put in the finish the documentation off.

Answer 8

Read "Code Complete" book, more specifically Chapter 11 about Naming. This is the checklist (from here, free registration required):

General Naming Considerations

Does the name fully and accurately describe what the variable represents? Does the name refer to the real-world problem rather than to the programming-language solution? Is the name long enough that you don't have to puzzle it out? Are computed-value qualifiers, if any, at the end of the name? Does the name use Count or Index instead of Num?

Naming Specific Kinds Of Data

Are loop index names meaningful (something other than i, j, or k if the loop is more than one or two lines long or is nested)? Have all "temporary" variables been renamed to something more meaningful? Are boolean variables named so that their meanings when they're True are clear? Do enumerated-type names include a prefix or suffix that indicates the category-for example, Color_ for Color_Red, Color_Green, Color_Blue, and so on? Are named constants named for the abstract entities they represent rather than the numbers they refer to?

Naming Conventions

Does the convention distinguish among local, class, and global data? Does the convention distinguish among type names, named constants, enumerated types, and variables? Does the convention identify input-only parameters to routines in languages that don't enforce them? Is the convention as compatible as possible with standard conventions for the language? Are names formatted for readability?

Short Names

Does the code use long names (unless it's necessary to use short ones)? Does the code avoid abbreviations that save only one character? Are all words abbreviated consistently? Are the names pronounceable? Are names that could be mispronounced avoided? Are short names documented in translation tables?

Common Naming Problems: Have You Avoided...

...names that are misleading? ...names with similar meanings? ...names that are different by only one or two characters? ...names that sound similar? ...names that use numerals? ...names intentionally misspelled to make them shorter? ...names that are commonly misspelled in English? ...names that conflict with standard library-routine names or with predefined variable names? ...totally arbitrary names? ...hard-to-read characters?