by Anthony Blackshaw · 18th January 2015

Writing poor quality code will dramatically reduce the time you get to spend doing things you love, if you’re lucky enough to leave a project shortly after such a contribution everyone who subsequently has to work with your code will think you an arsehole.

Above: This example is code found in a live and commercial project. Clearly the developer thought user.n5 would still clearly point to the 5th character of the user's name when used elsewhere.

The names we devise for folders, files, variables, functions, classes and any other user definable construct will (for the most part) determine how easily someone else can read and understand what we have written.

To avoid repetition in the remainder of this section we use the term variable to cover folders, files, variables, functions, and classes.

Be descriptive and concise

It’s the most obvious naming rule of all but it’s also perhaps the most difficult. In my younger years I would often use very descriptive names, I pulled the following doozy from the archives:

design_inspiration_competition_promotion_code_list

At a whopping 50 characters it can hardly be described as nondescript, however I’m sure anyone who came after would have cursed me for using such a long name. A far better name for my list of promotion codes would have been:

promotion_codes

Or possibly:

promo_codes

However care should be taken when using abbreviations or acronyms. Only use an abbreviated term if it is well known and/or its use is standard practice (e.g db, id, url, etc.) If you’re not sure if an abbreviated form of a term is well known err on the side of caution and don’t abbreviate:

p_codes

pcs

There is one exception to this rule - list or dictionary comprehensions (if you’re not familiar with list comprehension look it up). Using a single letter abbreviation in this case is preferential to a more descriptive name, for example:

The scope in which you declare a variable determines how much information must be included in the name. For example a variable declared in the settings module for a project will infer little information from its scope and therefore needs to be more descriptive.

settings.username = 'foo'

settings.db_username = 'foo'

Now consider the scope when the same variable is used in a function:

def connect_to_db(db_username, db_password):

def connect_to_db(username, password):

The purpose of our function is to connect to the database and therefore we can infer that the supplied username and password are for this purpose and there’s no need to include db in the variable names.

On occasion it may be necessary to use more descriptive names to avoid a naming conflict within the same scope. Consider our first example where we declared a username for the database in the settings file, what if the project uses multiple databases?

Pluralize when naming collections

Harking back again to my youth there was a time where I would have avoided using plurals at all costs, instead opting to follow the convention of appending _list to any variable associated with a collection of items. With the benefit of time I’ve come to prefer variable names that sound natural.

Reading your code out loud (or in your head if you’re attracting too much attention) is a sure fire way to spot badly named variables.

Above all else be consistent

When you work with old or externally written code chances are there will be difference in the rules the author(s) used when coming up with variable names. Unless you’re going to rewrite and maintain all the code in future do not break from the existing naming conventions.

If they prefix numbers with num_ or append _list to lists then follow suite, whilst conventional wisdom tells us two wrongs don’t make a right, mixing styles within a project will only make things worse.

Position	Name
Chair	Helen Troughton
Vice-chair	Sarah Stone
Secretary	Bridget Brickley
Treasurer	Sarahann Holmes
Publicity officer	Zillah Cimmock

If you have to work with code that has a mixture of styles or no clear style at all then I refer you to my opening statement.

Further reading...

• Code complete 2 (by Steve McConnell)
• The Art of Computer Programming: Volumes 1-4a (by Donald E. Knuth)