The name you give something conveys information about how you think about it. A properly chosen name makes the intended use of an item obvious without having to examine the context of its use. A poorly chosen name conveys no information or (worse) is misleading.
Variable names are an area where bad names proliferate with mad and depressing abandon. These names are amongst the most often created and also tend to be amongst the most badly selected. The following are some of the problems I've seen with variable names:
- Hungarian Notationised Hungarian Notation is thankfully rare in the managed code world. Modern development environments negate any alleged benefits it may have had. The internet is full of articles condemning this travesty so I won't repeat them here. Just say no.
- Needlessly Abbreviated Some developers seem to have a distinct aversion to typing. Hence they create variable names like 'lngRngFcst' where random letters (usually vowels) go missing. If the developer is particularly elderly (say in their 40s :) ) this may be a habit picked up from times when compilers had limits on the number of characters they'd recognise as significant. Regardless of the reason, it's bad practice.
- Arbitrary and Meaningless Some names convey no meaning whatsoever and exist purely because a name is needed. The use of i (and other single characters) as loop index variables is a very common example of this kind of name. This kind of name requires a reader of the code to determine its entire purpose from context. This may be simple in trivial code but any kind of complexity quickly requires juggling far more context than the human mind is comfortable with.
- Indistinct A variable name should make its purpose clear in its context. A name like 'sqlConnection2' doesn't do this. This tells me that I'm dealing with a database connection, but how does this connection differ from 'sqlConnection1' or 'sqlConnection3'?
- Easy To Mix Up Another problem with the names above is that they differ by only one character and are thus easy to mix up. Passing the wrong database connection to a method that drops all tables in preparation for recreating the table structure could be rather traumatic...
- Just Plain Wrong When a variable name described something other that what it actually contains you've got a bug just waiting to happen. It doesn't matter how well you document what it actually contains someone sometime will use it as the name suggests and not as it is used elsewhere.
The impression I get from talking to developers and reading their code is that too often they don't consider the longer term impact of what they're doing. Your 5 character line noise variable name has saved you a few keystrokes now (and with modern development environments it really isn't that many). But it's also slowed down anyone who has to understand the code later on. And unless you quit, are fired or get hit by a truck the person trying to work out what 'abgvr' does 6 months from now is probably going to be you.
So what kind of names should you as a developer be selecting. The following are some of the features I look for in a good variable name.
- Full Words I don't want to have to commit archeology or sociology to work out what words you mean in your variable name. Call a spade a spade, not a spd. If the extra time to type more characters is a problem for you, then you have much bigger issues.
- Unambiguous 'sqlConnection1' and 'sqlConnection2' don't tell me anything about how the database connections are intended to be used. 'sourceSqlConnection' and 'destinationSqlConnection' do.
- Concise You're not trying to describe everything possibly relevant to the variable in it's name. That's what the code is for. There is a level of tension here with the need to be unambiguous. When in doubt, lean towards unambiguity.
- Meaningful Sure it's funny to use a variable 'thisFrameworkIsCrap'. Until it gets you fired. Or it's 6 months later and you have no idea what the variable in the critical and buggy method does. Save your lame humour for blog posts.
- Accurate The name should clearly reflect the purpose of the variable. If the purpose changes then change the name of the variable to match rather than leaving it to mislead people later.
Changing a variable name is an easy refactoring that has generally good tool support. I therefore recommend that if you come across a variable name that is poor or misleading that you give serious consideration to improving the name. Generally the edit itself takes a few seconds, although selecting a better name can be non-trivial. And as always ensure that you properly test the change. Even considering these requirements changing variable names can be beneficial if it makes the code easier to understand for those who come after you.
Much of this discussion is relevant to the names of elements such as fields, method and types. I've chosen to start this series with variable names only to illustrate that these kind of improvements do not need to be wide reaching to be worthwhile.