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.
A collection of something. In software terms, it refers to a folder, location where files and data will be kept aside for later use.
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
Let's add a few more things to it. Based on this, if you have a function called
archive? in ruby), you expect it to give
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:
Try to keep the names of variables/objects as nouns and names of functions as verbs or instructions.
A function that validates something would be
validate_<something>. A file validator would be called
validate_file(...)and so on.
A file that has been validated should be called
validated_fileor even better, a
A function that shares credentials (with something else), should be
share_credentials(...)while the actual credential after sharing can be named
configfor an object and
configure(...)for a function.
Do not use multiple words to mean the same thing. I have seen functions like
retrieve_file(...)in the same code base. Stick to one and use that everywhere.
get_file(...)is my preferred option.
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.
Also, you don't need to suffix a variable with
_setto indicate the type of collection it is. In most cases, it is not relevant. So, prefer
Similarly, don't suffix or prefix data types when it is obvious. No need to use a variable
user_name_strto indicate that it is a string. Names are generally strings. So, we can omit the
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