As a graphic designer and illustrator who has created art assets for websites, apps, and even video games, I’ve come up with a battle-tested system for naming files.
File nomenclature (especially when it is for general usage) is a very divisive and opinionated topic. This article will go over some principles of file naming that are universal, as well as some edge cases to consider so that you can develop your own file naming system if necessary.
Keep in mind that much of this depends on the domain you are working in. There’s no universal system because certain applications have their own requirements (e.g. source code). I recommend that you follow existing rules for the domain that you are in.
But for everyday file naming – and especially art and design files – this is the system I use:
category-file_name-tags-v01.ext
Examples:
icon-moderator-dark-v01.png
icon-moderator-dark-v02.png
icon-user-dark.png
icon-user-light.png
icon-search.png
banner-expo_campaign-2021-02-05.jpg
From that, you can see how files are grouped based on their most significant category or attribute first. There are no spaces or illegal characters, so that they work in pretty much every environment.
That is my file naming solution for most of my projects. I’ve included my methods and wisdom from other domains and use cases so you can understand why I have adopted this naming system as my default.
I have a quick pro tip before we get started. If you use Windows, I recommend PowerRename in the Microsoft PowerToys suite of utilities to quickly rename batches of files. When you adopt a new system of naming files, you’ll want such a utility.
Principles
Style guides are very opinionated, so I want to go over some universal principles that are used to inform my naming system.
You’ll never know how your files will be used or where they will end up. Therefore, the file names should support the most expansive possibility of applications, usages, and operating systems. In other words, your file name should work on as many platforms as possible.
Rule #1: No spaces
There’s a lot of reasons why you shouldn’t use spaces in your file names. Dealing with spaces in the command line can be annoying. Spaces render out as an ugly %20 in web URLs. It can be annoying for programming or writing scripts.
Perhaps you don’t think you’ll ever use the command line or have your files hosted on the web. Trust me, you’ll never know the fate of the files you create, so it’s better to be safe than sorry.
Spaces are invisible by nature, so they can also introduce human error when dealing with them in file names.
For all these reasons, spaces should be avoided.
Rule #2: No capital letters
Some capital letters look like other lowercase letters or numbers. For example, “l” vs “I” (lowercase “L” vs uppercase “i”), or “O” vs “0” (uppercase “o” vs. the number zero). Having all letters be lowercase removes the confusion.
Capital letters are also prone to human error when typing them. How many times have you typed something like, “THank you?” Yeah, we all have. It is best to keep it simple by removing the possibility of error and save one extra keystroke per word.
Some operating systems are case sensitive while others are not, You may run into a situation where two files are copied over each other and one file is lost. This can happen because when one file was named invoice.pdf and the other was named Invoice.pdf. It is best to remove capital letters out of the equation to prevent that from happening.
When are capital letters okay?
In computer programming, capital letters may be required for your file names. For example, a file name for a class may have to match the class name exactly. In most cases, that would be PascalCase (the first letter of every word capitalized with no spaces).
Hyphens vs. underscores
In my opinion, this is the most subjective part of file naming: when to use underscores or hyphens. It usually never matters which one you use, but there are some cases where you have to use one over the other.
For decades, I’ve used underscores instead of spaces with no problems, but I’ve been experimenting with not using underscores over the past year.
As with capital letters, when writing software you have to follow the conventions of the programming language or the framework you are using. An underscore may indicate something special, especially if the file starts with an underscore.
Underscores in The Web
Underscores are less safe to use for files that are uploaded to the web. For the web, underscores shouldn’t be used in directory names or pages because Google recommends hyphens for URLs. I imagine that advice extends to file names as well (e.g., images, downloadable content, etc.), but I haven’t seen any opinion by Google on file naming for SEO purposes.
Underscores are invisible if the text is underlined, such as a hyperlink on a webpage.
All of that put together is why underscores are not recommended for the web.
Underscores in General Files
But what about files on your computer such as documents and design files? I have a hard time reading a file name if hyphens separate each word. I find underscores to be a more readable replacement for spaces. For most of my life, I’ve been using underscores for file names. I’ve used underscores for files that have been uploaded to the web and I’ve never ran into an issue. I feel confident using underscores instead of hyphens for file names as a general rule. And yes, my files have been accessed by Linux terminals, scripts, and the web. I’ve had good luck with underscores.
Underscores in Markdown
The only time I’ve ever run into an issue with underscores in filenames is when using Markdown to reference a file that started with an underscore. In Markdown, the underscore is used to indicate when to start and stop italic text. That’s the only time I’ve ever had a problem with underscores.
That is the reason why I’ve been experimenting with using hyphens instead of underscores; I’m doing more a lot more projects in Markdown.
Be Consistent
The important part of file naming is that the nomenclature is consistent on a per-project or per-domain basis. For example, a software project may have different naming conventions for source code files than the image files that the source code uses. This is okay; the consistency just needs to be per-domain.
My method for naming files
So with all of those principles put together, here’s how I name my files. I have a more “humane” version of this further down, which I’m using less and less.
category-file_name-tags-v00.ext
Principles:
- The most significant concept is first in the file name so files are grouped alphanumerically.
- Separate categories and tags with hyphens as the delimiter.
- Use underscores instead of spaces.
- All letters must be lowercase.
- Dates in file names must be in the YYYY-MM-DD format in accordance with the “most significant concept is first” principle.
- File names should be brief but descriptive.
Why do I use underscores for spaces?
Again, this is subjective, but the biggest reason is readability. I find hyphens to be poor separators of words, visually speaking. Yes, underscores are harder to type, but if your file name comprises a lot of words, you are probably naming it wrong. File names are not meant to be sentences.
A benefit of using underscores to separate words is that most user interfaces will treat underscores as part of the word if you double-click, or use SHIFT-CTRL-ARROWKEY to select the text. Essentially, this means that each category, tag, or name can be selected independently of the others very quickly.
However, for the past year I have been experimenting with using hyphens instead of underscores for spaces. I haven’t seen a significant benefit from doing this yet. It’s slightly easier to type. For Markdown files it can be necessary (as stated earlier). But at this point, it is still a soft rule for me.
Categories
“Categories” is a term I use to describe something that I want to group files into without making a new folder for them.
Here’s an example of some art assets:
grass-cut.png
grass-dead.png
grass-long.png
grass-short.png
dirt-dry.png
dirt-wet.png
See how this alphabetized file list is so easy to read? The grass and the dirt files are all grouped together.
Compare the above list to this list below, where we named them more traditionally with the adjective first:
cut_grass.png
dead_grass.png
dry_dirt.png
long_grass.png
short_grass.png
wet_dirt.png
See how the files are not grouped together? That is because we are not obeying the “most significant concept is first” rule.
Tags
A tag is a term I used to describe a slightly modified version of a file: version numbering, image size, or properties such as light mode or dark mode for that image. I write them as a postfix to the filename in order of most to least significant.
In this example, you can see how I have tags such as light, dark, and 600 to help identify if a file name is supposed to be on a light or dark background and if it’s a 600-pixel wide image.
shape-cube_silhouette-dark-600.png
shape-cube_silhouette-dark.png
shape-cube_silhouette-light-600.png
shape-cube_silhouette-light.png
shape-cube_silhouette-outlined-dark-600.png
shape-cube_silhouette-outlined-dark.png
shape-cube_silhouette-outlined-light-600.png
shape-cube_silhouette-outlined-light.png
space-distance-dark-600.png
space-distance-dark.png
space-distance-light-600.png
space-distance-light.png
space-position-dark-600.png
space-position-dark.png
space-position-light-600.png
space-position-light.png
This provides a nice rhythm to the file names, making it easy to find what I’m looking for in a filename list.
Should a version number go before or after the tags?
It depends. Always follow the “most significant concept is first” principle when figuring out what tags go in what order.
My instinct is that the version number of a document will always be the last part of the file name, but there are times where you may not want that to be the case.
In the example of a logo file, where I have a dark and light mode, I usually have the dark and light mode version in the same source file. For example, logo-v06.afdesign is an Affinity Designer file that includes the artwork for the light and dark mode versions of the same art asset. My export options in the source file will add a -light and -dark string of text at the end of the file name, so the final will be the following:
logo-v06.afdesign
logo-v06-dark.png
logo-v06-light.png
Note that the version number is not last. That is actually the preferred scenario for me in this case where the dark and light files are inside of the source .afdesign file.
Make file names “sticky” by using two underscores at the beginning of the file name.
When I have a file named __readme.txt, the underscores at the beginning of the filename will sort it to the top of the list. I also use folder names called __old to sort them separately.
Why do I use two underscores instead of just one? It’s more noticeable. It’s closer to one em’s worth of length, and I like having the text indented out a little bit more.
The only time this has been a problem is when using software that incorporates linking to Markdown files, such as the note-taking app Obsidian. Underscores are used to indicate italics, or two underscores to indicate bold text. That means the text starts to format as bold if I link to one of those files.
Alternately, make files sticky by starting them with a string of zeros.
This is the more future-proof method of making a file name sticky.
When using underscores in a file name is inappropriate, or if I want to force a very specific ordering system, I’ll use a string of numbers at the beginning of the file name.
000-scratchpad.md
010-the-big-picture.md
020-choosing-your-tools.md
030-the-elements-of-design.md
Any file starting with 000- is considered sticky, as it will always show up at the top of the filename list.
I start my numbering at 010- and then increment each file by 10. If I need to insert a document in-between 010 and 020 I can use 015- without renaming every file in the directory. This is a system I have to use when writing structured content in Markdown because of how Markdown uses underscores for text formatting.
When I use hyphens instead of underscores
When I’m working on web site projects, the names for pages and directories should use hyphens instead of underscores. The reason why is because it is the standard for URLs to use hyphens to separate words because they are easier to type. From a technology standpoint, Google treats hyphens like spaces, but underscores are treated as word characters. That is why the double-click and CTRL-SHIFT-ARROWKEY trick works to select a string of text like file_name.
Google will drop the underscore and consider a word like “company_logo” as “companylogo” (all one word). That might be a problem for SEO, but I haven’t seen any definitive research or statement on how that applies to file names on the web, just URLs.
I think that image names with underscores should always be fine though, even for web projects. To this day, I use hyphens for images. I haven’t ran into any problems or concerns. If you want an image to show up in Google image search, it may be prudent to use hyphens instead of underscores. But that’s just a guess.
The humane version of my naming scheme
Let us assume that you are not going to interact with a file using a command-line interface or upload it to the web, and you just want your file names to looks as readable as possible in your folder view. You can use the same principles of the naming scheme but modify it slightly to use spaces and capitalization.
Category - File Name - Tag - v01.ext
This follows all the same principles of my previous naming scheme, except that I don’t use underscores; I use spaces and - or “space hyphen space” as the delimiter between file names, categories, and tags. Categories and tags are capitalized. The file name can be title case or sentence case, whatever case makes sense.
Advantages:
- It’s a lot more readable.
Disadvantages:
- The file names are longer.
- The files will create ugly URLs if those files ever make it to the web.
- The files are more difficult to work with through a command line.
When do I use this naming system? If I’m reasonably sure that the files won’t be accessed directly through the command line (since dealing with spaces can be a pain), and it will never be put on a web server. I also won’t use this system if the length of the file names may become a problem. An example of this would be video or graphics software, where it may show a list of art assets used within the project. That list takes up a lot of screen real estate, and if the file names are too long, I won’t be able to see the entire file name. The human-readable filename of Category - File Name - Tag - v01.ext uses 6 more characters than my standard naming system, which increases the length of the file name by 20%.
I do use this naming scheme on a semi-regular basis. I use it for text documents, talks, presentations, anything that I know won’t get uploaded to the web anywhere (except contained in a ZIP file) or used as an art asset for a bigger project. In short, this is my lazy naming scheme if I want things to be readable. But if I’m doing something for a project, I’ll stick with the more robust and condensed naming system.
