How often have you found yourself searching for that shell command you have used 755 times before? What makes the incantation so hard to remember? Maybe it involves a string of seemingly random characters, something a lot of older Unix packages are guilty of, or maybe the choice of terminology is poor.

Software, like many geekdoms, is full of pop-culture references, acronyms, made-up words, and puns. This tangled web of jargon can lead to confusion and drive new-comers away. If you are writing a commandline package then its name, subcommands, config, and all other terminology needs to be simple and descriptive.

An example of a package which uses poorly chosen terminology is the version control system Git. If you have ever used Git then you will have committed changes. These changes must be staged, which is done by adding the change to the index; to view the index the command git status is used. Stage, add, index and status. Four terms have been introduced to refer to what is in practice a straight forward concept. In the source code these four concepts are probably distinct but to the user there is no need to introduce so many when fewer, more carefully chosen, terms could have done the job.

When deciding on a naming scheme there are a few things to bear in mind. First and foremost is to make the names easy to understand. Ensure that people have a good idea of how a concept fits into the project from its name alone. A technique commonly used for choosing terms is is to pick a metaphor. Metaphors are useful because they can show how terms relate to each other as well as doing a lot of the work for you when you need to find names for new concepts. For example maybe you are writing an image editor: the metaphor could be painting, the tool to add some pixels might be called the paint brush, the tool to remove pixels could be paint-stripper, and so on.

Choosing a naming scheme is not easy, but thankfully a lot of areas of software have pre-existing naming scheme norms. For example if you go to a website and it talks about comment then you have a good idea of what it means. If you avoid well established norms it can even lead to additional confusion.

Another point, worth noting, is to consider how words are pluralised. There do exist projects where people have been confused by the plural of a word not being obvious. For example if you have a script which creates pictures of sea-creatures, then to generate an octopus you might run ./sea-creatues --octopus, and to generate a picture of more than one octopus maybe ./sea-creatures --octopodes. Although octopodes is a real word it is not obviously the plural of octopus. Try to choose words which pluralise simply in English (ie. by appending the letter s).

Next time you write a piece of software, put some thought into the terminology: is it easy to understand or is it jargon? Using puns and pop-culture references rather than a simple metaphor may amuse a minority of people but it is likely to put others off.