File naming and organization for personal and team use.
Introduction
File naming and hierarchy are essential to finding the location of files you’ve previously worked on; this is even more important when working with a team on a project. With a good file naming convention, you know what to look for and where to look because you can infer the name and location from the pattern and logical hierarchy. So, what makes a good naming and organization convention? An excellent organizational scheme should cover all of the following:
- Well-thought-out and structured directory hierarchy
- A clearly defined character set, which causes no issues with any tools, operating systems, or web interfaces used
- A general file pattern that you can apply to all files, not just officially released ones
- Concise and not overly complicated rules so anyone can name or locate a file using it
- Proper use of file extensions for file types
- Carries documentation to improve clarity further
I collected the information in this article over several years from studying different operating systems and company organization schemes, including what is used by Fortune 100 and 500 companies and standard large universities that published their organization methods.
Directory hierarchy
Directory hierarchy is fundamental to an organization scheme; it lets you know where to start looking for a file by asking yourself what it is and what it pertains to. So, what does a good directory hierarchy look like? A good directory hierarchy allows you to gain information about the files stored in it by looking at the path to the file. Some examples of this:
/Business/Marketing/Pictures: from this path, you can tell that these images are related to business marketing./Resources/Templates/LibreOffice: this path lets you know there are general templates for use with LibreOffice stored there./Archives/Employees/Johnny_Blaze: this path indicates that the content is archived employee files, and the last part is each employee’s name. The hierarchy can use dates to group content taken or created on a particular day or date range, commonly done with pictures. You may further organize/Business/Marketing/Picturesfrom above using dates like/Business/Marketing/Pictures/YYYY/MMor/Business/Marketing/Pictures/YYYY/MM/DD. Adding the day to the path would be used in cases where a lot of content gets created each month, making the day subdivision more useful. You can use directories to help convey ownership if you’re working on content for several clients. An example would be:/Projects/ClientName/ProjectName, where the projects under the client’s name belong to the client. Further, the contents of the project belong to the project.
Specific things to avoid in a directory hierarchy that can make a mess or confuse users:
- Top-level directories with similar names or which could be subdirectories; examples of this are
/Businessand/BusinessDevelopment, both as top-level; in this case, you’d want to move/BusinessDevelopmentto/Business/Developmentkeeping content related to advancing the business vs. general operation stuff separate but still related. You may also consider relocating/Business/Marketing/Picturesto/Business/Development/Marketing/Picturesunder this new layout. - Storing unrelated content under a directory that does not make sense, such as keeping general templates under
/Projectsinstead under/Templatesor/Resources/Templates/AppTheTemplateIsForwould make more sense. - Duplicating names of directories in subdirectories such as
/Documents/DocumentPicturesin this case, you’d change this to/Documents/Picturesor relocate it to/Pictures. - Using the words
files,directory, orfolderin conjunction with the content of the directory, examples of this would be/PictureFilesor/EmployeeFoldersorImportantDirectoriesin all these cases, the directory names would be better and shorter without the unneeded words added to them.
File naming
Several things go into making a suitable filename, the most crucial being consistency in the names and where the files are stored, allowing users to find them easily. The following section will cover the different parts of file naming and why it should be that way.
Be concise and avoid long names
Filenames and directory names should be concise and avoid being long or drawn out, making things more challenging to find; in addition, words like a, of, to, and the should be avoided. For example, the filename: The business meeting about making the best use of open source in production 2023 January 5th.odp is terrible. Renaming it and relocating it to /Business/Meetings/2023/01/OpenSourceForProduction.odp or if the file is not part of a collection Meeting-20230105-OpenSourceForProduction.odp both of these cases are much improved over the first.
Avoid special characters
It’s best to avoid special characters in filenames because operating systems may interpret them as having a defined function, which can have strange adverse effects or break automation; this generally includes: `, !, @, #, $, %, ^, &, *, (, ), =, +, [, ], {, }, \, |, ;, :, ', ", <, >, /, and ?.
Windows generally will not allow the use of most of the above characters as it’s the most limited modern OS available.
Avoid using blank spaces
Why avoid space in the names of directories or files? All major file systems support the space character ext4, xfs, btrs, hfs+, ntfs, apfs, and fat32. In addition, all modern operating systems have support for Unix (1978), macOS (1985), Linux (1992), and Windows (1995). Well, using blank spaces in filenames should be avoided for several reasons:
- Some applications don’t recognize white space properly and may treat files differently than expected; you can observe this behavior on Windows, Linux, and macOS.
- Some search tools don’t operate correctly on files containing spaces.
- Windows, Linux, and macOS command line applications require extra work to handle spaces properly.
- The space character is unsafe because significant spaces may disappear, and insignificant white space may get introduced when URLs are transcribed, typeset, or subjected to the treatment of word-processing programs RFC1738.
- Universal paths cannot contain spaces, which results in no copyable/pasteable links unless done only via the web browser, as the Windows file manager and many Linux file managers don’t correctly handle URL encoding.
- Spaces are less visible than other characters, resulting in common double whitespaces or blank spaces in strange places.
Define general separators
A suitable file naming pattern requires two types of separators. The first is the general word separator used between words in a filename. The _ underscore is the defacto standard for word separators in most local or web-based naming conventions and is the most visually similar to a space character. In some naming schemes, the word separator does not exist; instead, filenames use title case. The second separator divides filename elements, such as document number, date, version tags, etc. The most common separator for this purpose is the hyphen/dash -.
Case and Title case
Companies or users may prefer the look of title case over underscores in filenames because title case does not offer any adverse effects as white space does; Some use it instead of whitespace or underscores. So instead of a filename like Doc-New_Element_for_Fusion.pdf, it would be Doc-NewElementForFusion.pdf. Even if you choose not to use this option, writing each word’s first letter capitalized is still preferred vs. using fully lowercase or entirely uppercase for file names, with the latter reserved for abbreviations.
File extensions
Filenames for all types should include a file extension except executables on Linux and macOS, as it’s common for those types not to have a file extension.
Version/Revision numbers
In systems that don’t have revision control built-in, having the version of a file may be essential to distinguish a file from an older version that might have breaking changes or changes in decision. Typical schemes for version numbers include using vN, for example: Policy-v2.odt, or using a simple letter A-Z, usually capitalized, for example: Policy-A.ods.
Another use of version numbers is to indicate a run of a long-running test, for example: Pressure_Test-T20.csv for the 20th run of the test.
Using dates
The date is often included in a filename when the file is time-sensitive or pertains to a certain period, such as taxes or event itineraries. If a file is part of a collection like pictures, it’s generally better to use the hierarchy YYYY/MM/DD and store the photos for that day in that date’s directory. In the case where the date may be in the filename, general practice is using either YYYY-MM-DD or YYYYMMDD only using as much of the date as needed and attaching it to the filename like so: Business_Taxes-2023.zip, Vacation-202305/, System_diagram-20230501.drawio.
Another method used to represent dates is in quarters of a year, which often have a year followed by a quarter YYYY-qN, such as Report-2023-q2.pdf.
Using unique identifiers
Some companies may attach unique IDs to documents, allowing quick look-up in systems that provide search, such as Nextcloud. The unique IDs are often between 4 and 16 numeric or alphanumeric characters. The pattern or method to create these unique numbers ranges from random generators to ones based on information such as date, client, and content type. These IDs are also more commonly used for official files than individual notes or experiments.
Use of abbreviation
Using abbreviations can significantly shorten the filename length and make files more manageable; however, overuse can make files hard to understand and locate. Use commonly known abbreviations or abbreviations within known fields of study of users. Only use obscure abbreviations if they are part of the general knowledge needed for a project.
Using personal names
When used in filenames, the general way is to have the last name first, the whole first name or first initial, and optionally the middle initial. An examples of this: Email_Export-Blaze_Johnny-2023-03-01.zip or Gmail_Takeout-StarkT-20231010.tar.gz
Pattern and use of elements
A file naming pattern has several required and optional elements connected by a chosen separator in a particular order. Unlike the rest of the content in this article, file naming patterns seem more diverse. Since there is no typical pattern, here is a generic one from the elements used in this article: [client-][project-][collection_type-]content_title[-person][-v(version) or date].extension. Here are some examples of files using this pattern:
Apple-iPhone16-Design-Main_CPU_Architecture-v1.pdfDatasheet-RP2040-2023.pdfCost_Analysis-q1.odsssh_key-Blaze_Johnny.pubG60_Sword-Review-20150608.md
As you can see by these example filenames, it is easy to locate any file by simply asking yourself what it is.
Guide
After defining a naming and organization system, it’s a good idea to document it as a guide or a cheat sheet. The whole naming and organization scheme should be compact and simple enough to fit on a single note card, making it easy for anyone to memorize quickly and use. Additionally, it should follow logical organization, so the location of files should be guessable even without a guide.
