Take a minute and look at some of the files and folders on your computer. What do the names look like?
Sorry, that probably wasn’t very clear. Specifically, I want you to see if there are spaces in your file and folder names. My guess is probably! Mine certainly had spaces before I learned more about computers and got involved in Git and the command line.
Take another look at some files/folders. What is your “capitalization scheme”? Is there a pattern? Do you name your files by what they contain? Do you have dates in your files? Do you have a group of files with something like “File First Draft”, “File Second Draft”, “File, revisions from colleague”, etc.? All of these can be problematic for computers and even more so for humans interacting with computers.
The following chunks go through my opinions on file naming conventions. But that’s what they are: opinions. Suggestions. Following them will make your life easier later on. But by all means, go ahead and ignore me and decide for yourself later if you want to make a change. I probably won’t pop up in your home and check your file names. Try not to get too lost with these; an extensive example will be provided at the end of the section.
Subsection 1.1.1 Naming Conventions
File Names With Revisions.
You might be familiar with this situation: You write one draft, get feedback, save a second draft as a new file, get feedback again, and finally make a new file with a final draft. Then, you decide to make modifications to that final draft which is saved as a new file, etc., etc.This is great until you realize that now you have way too many files for a single document. How do you know which one is real final draft? What if you open the wrong one and start editing? Now you have to edit all of the files to make them match.
Sure, a computer can handle that many files and doesn’t really care how many drafts or revisions you have. But more files take up more storage space and increases the chances of confusing you! How on earth can we solve this problem? It’s not like there’s a magic software that can keep track of all of our changes in a single file.
Ah, but there is! This magic software is called Git. Git specializes in version control which means that you do not have to worry about twelve drafts. Git keeps track of your revision history for you. If you are familiar with Google Docs, Git is very similar. Docs saves your changes and makes it easy to revert back to an old version if you change your mind on anything.
For now, don’t worry about Git; we will get there in
Chapter 4. Just know that after reading this book, you won’t have to worry about excess drafts and should never have to save so many drafts again.
File Names With Dates.
Ok, this isn’t entirely problematic. But I never understood why dates in file names had to be so specific. Having years makes sense, maybe months. But days? Times? Seconds? Once you start getting that specific with dates and times, you run into the same issue as in
File Names With Revisions. Dates and times just make your file names incredibly long, hard to read, and hard to use in the command line. Please try to avoid dates, other than years, perhaps.
Descriptive File Names.
File names should be descriptive! Furthermore, they should describe what the file actually contains/is about and not some random name. Probably most of your files are descriptive? That’s great! But what’s the catch? File names should also be short. Short, sweet, to the point, and also descriptive.
That’s pretty tricky, you might say. Sure, I respond, but you can take advantage of abbreviations and word-shortening tricks. For instance, suppose I had a file name like this:
Chapters3_4_Overview of Sampling and Simple Random Sampling (SRS).pdf
This is clearly descriptive. We know exactly what this PDF is about: it refers to chapters 3 and 4 of a textbook which is about sampling in general and digs into simple random sampling. But wow, it’s really long. On my computer, it shows up as
Chapters3_4_Overview of…SRS).pdf
Now do you know what this file contains? I don’t. Yes, it’s on chapters 3 and 4 but we are left hanging as to what the chapters are an overview of! Moreover, what does the random “SRS” mean at the end?
If it were me, I would rather name this file (based on the conventions discussed so far)
Ch3_4_Sampling and SRS.pdf
Wow! So much shorter. Do you still have an idea of what the file contains? Hopefully! “Ch” is usually accepted as an abbreviation for “Chapter” so it is clear that this file is over chapters 3 and 4. The subject of these chapters is sampling and simple random sampling (“SRS” is a widely-used abbreviation in statistics for simple random sampling).
File Naming Trick.
An easy way to shorten file names is to remove the vowels from words. The human brain is incredible in that it can determine what a word should be based on a small amount of context. Assuming the file above was in a folder pertaining to statistics, I could shorten it even more:
Ch3_4_Smplng and SRS.pdf
And we still know what it’s about!
A quick word of caution. Take care not to over-abbreviate. It may not be necessary to abbreviate every word. For instance, I wouldn’t change “you” to “y” or “gate” to “gt”. You may be confused later: does “gt” mean “gate”, “git”, “get”, “gut”, “agate”, etc., etc.?
Summary: keep your file names short and to the point. Describe what the file is (I wouldn’t name the file above “bananas.pdf”!).
File Names With Spaces.
If you only follow one convention in this section, this would be the one. This the most important for working with the command line. Spaces in file names increase the amount of typing you have to do and make it more difficult to understand what’s going on on the command line.
For instance, suppose I wanted to open the file we discussed earlier. On the command line, I would open the file like this (don’t worry about the commands, just notice what it looks like):
open 'Chapters3_4_Overview of Sampling and Simple Random Sampling (SRS).pdf'
I could also do it like this:
open Chapters3_4_Overview\ of\ Sampling\ and\ Simple\ Random\ Sampling\ (SRS).pdf
First, notice how long these titles are. That’s a lot to type! What you should really notice is that in the first example, the file is surrounded in quotes and in the second, there are a bunch of backslashes. For each file name with spaces, you have to either remember to enclose the entire name in quotes or to take the time to put a backslash before every space. It may not seem like too much of a hassle, but you will get annoyed with it pretty quickly. It also can cause setbacks inside code editors when you want to import or export files with spaces.
So what do we replace the spaces with?
Personally, I use snake_case for file names and kebab-case for folder names, just to help me keep them separate and still easy to read. I also tend to name my files and folders with lowercase letters if I can.
Using the shortened file name above, I would use the following as my file name:
ch3_4_smplng_srs.pdf
Note that I got rid of the “and”. Cases are useful in that they make it easy to remove articles and prepositions which in turn helps us keep file names nice and short.
It is also important to keep your file names consistent. If I had another file about chapter 5 of this textbook which is about cluster sampling, let’s say, I would want to name it something like
ch5_clstr_smplng.pdf
Notice that the structure is the same as before: first I have “ch5” to represent the chapter number, then I describe the chapter with “clstr_smplng”. Like before, I use snake_case and I made sure to use the same abbreviation for “sampling” as I did before. Consistency is key for our own sanity and so we can quickly scan for the file we need.
It’s worth repeating once again. File names should not contain spaces. Files about related content should have a similar naming scheme.
Sorry, once more. This time, I’m going to yell. File names should not contain spaces.
A Quick Note on Folder Names.
Folder names should also follow all of the conventions above. This is a lot harder to get used to. I still feel like I’m breaking the Human Code of Folder Names everytime I ignore spaces and capital letters. For whatever reason, I’m fine with file names, but folder names just don’t feel right.
But too bad for me! I name my folders according to the conventions anyways. And you should too. (As I mentioned earlier, I use snake_case for files and kebab-case for folders. You might consider doing so as well; they are the two most popular cases.)
