The Linux Philosophy for SysAdmins, Tenet 10 — Use common sense naming

Author’s note: This article is excerpted in part from chapter 12 of my book, The Linux Philosophy for SysAdmins, with some changes to update the information in it and to better fit this format.

Typing is not my forte and the Lazy SysAdmin does everything possible to reduce typing. I take that seriously. This tenet expands on that but there is much more to it than just reducing the amount of typing I need to do. It is also about the readability of scripts and naming things so that they are understandable.

One of the original Unix philosophy tenets – although one of the lesser ones – was to always use lowercase and keep names short. An admirable goal but not one so easily met in the world of the SysAdmin. In many respects my own tenet would seem a complete refutation of the original. However the original was intended for a different audience and this one is intended for SysAdmins with a different set of needs.

I think the ultimate goal is to create scripts that are readable and easily understood in order to make them easily maintainable. And then to use other, simple scripts and cron jobs to automate running those scripts. Keeping the script names reasonably short also reduces typing when executing those scripts from the command line but that is mostly irrelevant when starting them from another script or as cron jobs.

Script and program names

If you explore all of the original GNU core utilities you find that their names are quite short – many of them being two or three letters. This is great but there are are thousands of Linux commands overall and only so many meaningful short combinations. One property of any name should be that it has some meaningful connection to the purpose of the program or script.

Use of capital letters in some of the names, such as NetworkManager.service do help make it easier to discern the function of the script but they also make it just a bit harder to type the names on the command line. And, of course, NetworkManager.service is relatively long, but most of the commands are based on the top level, nmcli.

One example is a very nice program called mtr which is an interactive replacement for the old traceroute program. The mtr program maintains an active and continuous traceroute with a dynamic display that shows the number of packets lost at each hop and can show multiple routes for if the packets are being rerouted for some reason. Very interesting and useful.

The mtr program was originally named that because a person named Matt Kimball wrote and maintained it. Therefore it was “Matt’s traceroute.” After Matt stopped supporting it, Roger Wolff took over. It is still named mtr but that now stands for “my traceroute.”

Naming scripts with very short names can be a challenge because many of the existing short letter combinations are already taken. I always try to do some research when naming a script to ensure it won’t cause a problem with an executable already installed on my computer. I usually do a quick check with the which command.

Since you probably don’t have the mymotd script on your host in any of the standard executable path locations, if at all, it should not appear when we use the command below.

# which mymotd
/usr/bin/which: no mymotd in (/usr/lib64/qt-3.3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/root/bin)

The which command displays the paths it searched in its attempt to locate the specified executable file. If the mymotd script is installed /usr/local/bin, which is the correct location in the Linux FHS to store locally created executable files, the result is different.

# which mymotd
/usr/local/bin/mymotd

Not all conflicts will arise when you first write a new script. After checking the installed programs, I also do a Google search. I try to find any information out there about programs that might have a naming conflict with mine. Longer names are much less likely to conflict but they don’t really need to be too long.

Naming scripts can be a bit tricky with potential conflicts like this. One reason I like to use script names that are a bit longer, say four to eight or ten characters, is to help prevent naming conflicts. I sometimes add an uppercase letter to my script names to help it stand out and help to clarify the name a bit in a long list.

The bottom line here is that the name should be memorable and meaningful – to you as well as well as other SysAdmin, easy to type, and easy to spot in a list. Those are my personal criteria. You may have others and that is perfectly fine. Just remember that other SysAdmins may someday need to work with the hosts on which your scripts are located.

Variables

Back when I purchased my first IBM PC in 1981, I ordered it with the maximum of 64KB on the motherboard while the cheapest model had only 16K. That was not a lot of space in which to work. BASIC was included with the PC in an on-board ROM and made a good choice for many people learning to program in those days.

Because of the limited space it was important to be frugal with memory usage when writing programs in BASIC. I did not do things to make it look pretty like indent loops and subroutines because each tab or space took up one Byte of memory that might be needed for something important. I kept variable names as short as possible. I typically used single letters or two-character variable names with a letter and a number such as A7. Comments were non-existent if we wrote fairly large programs because there was not space for them. I did all of this to save memory but it made my programs very difficult to read.

I wish I had saved some of the really horrible code I have either written myself or some that I had to fix which was written by someone else. And there has been a lot of both.

Naming variables

I tend to make my script variables long enough to be indicative of their content. Those variable names were lengths ranging from fairly short to moderate. All of them were designed to make it easy for myself and future script maintainers to read and understand the code.

The variable names in my scripts tend to reflect their content. Thus you should be able to deduce that a variable named $CPUArch probably contains information pertaining to the architecture of the CPU. You might not know the exact type of data, but you should have a general idea what to expect when you view the contents of that variable. You would probably expect to see something like “X86_64” or just “64” for the value of this variable. At least in my scripts, that would be the case.

The thing to keep in mind is that variable names are only typed while writing and maintaining the script. The script can then be run as many times as needed and I never need to retype any of those variable names.

Make everything a variable

This is a pretty common best practice. Even if you need to use “constants” like Pi, or Euler’s constant, or constants related to a specific field of endeavor, they should be declared as variables and then the variable used in calculations. Of course bash itself does only integer arithmetic but there are other types of variables.

Procedures

Bash is a command line language that supports the use of procedures. Procedures in scripts need names just as variables do. The script we created in Chapter 11 contains a few procedures that are named to provide an insight into their function.

For example, the Help() procedure is obviously intended to print help information and the GPL() procedure prints the GPL license statement. The kb2gb() procedure is a bit more obscure but with only a little consideration it should be clear that it converts Kilobytes to Gigabytes.

Hosts

Yes, hosts – computers on a network – need naming. Most organizations have some sort of convention for naming hosts. Most of the SysAdmins I know have established some sort of conventions even if their organization has not imposed one.

One place I worked used the major Greek and Roman gods to name their Linux servers while their Unix and Linux workstations received the names of lesser gods and mythological personages. Other places have used names from Star Trek or Star Wars for their hosts.

Most SysAdmins have home networks and we all have some sort of naming convention that we use. Whether based on gaming, mythological gods and characters, kids and grandkids, birds, pets, ships, movies, states, minerals, sub-atomic particles, chemicals, the names of scientists, or whatever, I have seen many different conventions used. I use the names of Essex class aircraft carriers for most of the hosts in my home network as a tribute to my father who was on one of them, the Bunker Hill, in the Pacific during WWII. For a two-word name like that I just run the words together to create, “bunkerhill”. By convention host names are always in lower case. A little testing will reveal that the Internet DNS system ignores case when performing lookups but I do like to go with convention for things like this.

Organizational naming

Many organizations have well defined naming conventions while others leave those details up to the System Administrators. A couple of the organizations I have worked for had conventions for naming hosts, other network nodes, programs and scripts. I think this is a bit overkill, but it is better to have an extensive and well-documented convention than none at all.

Most of the places I have worked had naming conventions for network hosts and nodes but most of the lower level naming such as scripts was left to the SysAdmins. This is my preferred situation. Most organizations do not need to deal in such detail with naming conventions.

Whatever conventions you have at the SysAdmin level should be well documented.

Summary

As with other tenets of the Linux Philosophy for System Administrators there is not one particular “right” way to do things when creating names for files, procedures, scripts, variables, and anything else. It really is about what works best for you. You should feel no pressure to name things in any particular way other than what makes sense and is meaningful to you.

Common sense in naming is the real key here. The main criteria I use is, “will this name be meaningful to me or another SysAdmin in a few years when the script needs to be maintained?”

The use of common sense by SysAdmins when naming things contributes to our objective of being the Lazy SysAdmin. Code that is easy to read takes far less time to maintain than code that is not. Having to maintain poorly written code that is unintelligible until it has been completely rewritten sucks up huge amounts of time and effort that would be better spent elsewhere.