Archive vs Archived | A rant on naming things correctly

We are always taught that grammar is important in English (or any other language for that matter). But somehow it is not the case with English usage in programming, most of the time. The Grammar rules seem to be relaxed when people are coding.

My students and my colleagues know how particular I am about naming things in code. It is something I take pride in. Apart from picking descriptive names, I also try to make sure that the Tense and Number of the variables or functions, always agree with the Grammar rules.

I review a lot of code daily - of my colleagues, my students, etc. Even though I am less critical of other people's code than I am of mine, one of the things I do try to give feedback on is about adhering to the correct grammar. It happens to be one of the most common mistakes I see. They use the correct word to name something but often in incorrect tense and number than what it is supposed to be.

The latest installment of this is the misuse of "archive" and "archived" in code by a student. And hence this article.

Let's get the definitions first.

archive /ˈɑːkʌɪv/

(noun)

A collection of something. In software terms, it refers to a folder, location where files and data will be kept aside for later use.

(verb)

The act of storing or placing something in an archive.

So, you can use them in sentences like:

1. I am placing the files in the archive. (Noun)
2. I am archiving the files. (Verb)

Archived, is the state of an object or a file after it has been placed in an archive.

Once you know these, you can name the variables and functions that use this word, correctly.

For example, the folder where you are storing the files would be called an archive. A file you have archived would be named archived_file. The function or method that archives a file can be called archive_file() or maybe simply archive().

Let's add a few more things to it. Based on this, if you have a function called is_archive (or archive? in ruby), you expect it to give True or False based on whether something (a folder) is an archive, or not.

To check if a file has been archived, you will have a function called is_archived that will take a file name.

Here's a sample code (in python) that shows all of this in action:

archive = Path('/opt/archive')

is_archive(archive) # True

files = os.listdir(current_dir) # Get all files in the current directory

# Archive the files
for file in files:
  archive(file)

archived_files = os.listdir(archive)

for file in archived_files:
  is_archived(file) # True

You can use similar conventions in other languages also.

Now, for some general advice on naming things from my experience reviewing code for years:

1. Try to keep the names of variables/objects as nouns and names of functions as verbs or instructions.

2. A function that validates something would be validate_<something>. A file validator would be called validate_file(...) and so on.

3. A file that has been validated should be called validated_file or even better, a valid_file

4. A function that shares credentials (with something else), should be share_credentials(...) while the actual credential after sharing can be named shared_credential.

5. Use configuration or config for an object and configure(...) for a function.

6. Do not use multiple words to mean the same thing. I have seen functions like get_file(...), fetch_file(...) and retrieve_file(...) in the same code base. Stick to one and use that everywhere. get_file(...) is my preferred option.

7. Do not use a variable in the plural when it only has one value. Similarly, when a variable will have multiple values, use a plural. So, if you have a variable containers, it is expected to contain multiple containers.

8. Also, you don't need to suffix a variable with _list or _set to indicate the type of collection it is. In most cases, it is not relevant. So, prefer objects instead of object_list and files instead of file_set.

9. Similarly, don't suffix or prefix data types when it is obvious. No need to use a variable user_name_str to indicate that it is a string. Names are generally strings. So, we can omit the _str suffix.

10. Use similar forms of words when referring to similar things. For example, if you are referring to states of a docker container can be in, don't use "Running, "Success" and "Fail". Keep them all in one grammatical form. Something like "Running", "Succeeded/Completed", "Failed". That reads better.

I can go on, but I will stop this list here before it gets too pedantic.

Hopefully, all of this information has been useful for you. If not, you can let me know all about it on Twitter @durgaswaroop