wiki:faq/files/choosing-names

How should I choose the names for files in my web site?

As an author of a web site, you'll be uploading files for other people to view, download, and link to. Choosing good names for your files helps to make them more accessible to people.

Use Simple Characters

It's a good idea to choose your file names so that they only contain lower-case letters (a-z), digits (0-9), underscores (_), hyphens (-), and periods (.).

Avoid upper-case letters because it makes the URL pointing to the file difficult to communicate to other people precisely if they're not following a link. Other punctuation characters (including spaces!) should be avoided because they are not allowed in URLs, and will need to be escaped. For example, if i have a file named "color brochure.pdf" i'd need to link to it with http://www.example.org/color%20brochure.pdf because the space character would be escaped into "%20". This mars the readability of the URL, and makes it more difficult to say to someone over the phone, or to jot down on a napkin.

It would be better to call the file colorbrochure.pdf or color-brochure.pdf.

Choose Content-Specific Names

When choosing a name, think about how to make the name not only relevant to the content of the file, but also how to make it distinct from other files that it might get confused with. For example, even if you currently only have one color brochure for your organization, color-brochure.pdf might not be as good a file name as campaign-color-brochure.pdf, because next week you might make a color brochure about some other aspect of your organization.

Handling Versioned Names

Say you plan to upload a new version of campaign-color-brochure.pdf. It's tempting to call the file something like "new-campaign-color-brochure.pdf". While this makes sense in the short term (to keep the versions apart), the next time you decide to change the order form, the name will be pretty confusing. (e.g. "should i replace the old new-campaign-color-brochure.pdf with the new new-campaign-color-brochure.pdf?")

In addition to "New", the same concern stands for terms like "Final" or "Fixed" -- these terms don't really belong in a published filename because their meaning is eventually invalid (e.g. once there's another draft, or a new problem uncovered). This causes confusion when you have to work with them later.

So what should you do? In general, you should provide files with names that only describe the resource, not the version. If you really need to keep a version history around, and you want to keep track of it by differently-named files (there are other methods you could use too!), you should either use explicit version numbers (e.g. campaign-color-brochure.v4.pdf) or timestamps (e.g. campaign-color-brochure.2007-11-01.pdf). And you'll often want to provide a versionless alias to the resource as well, so that people who don't care about the version will get the latest one (e.g. campaign-color-brochure.pdf should point back to campaign-color-brochure.2007-11-01.pdf, if that's the latest version of the file).

Durability of Names

Note that once you change the name of a resource, you'll need to go back and change anywhere that links to it. For a public resource (e.g. a webpage, or a file offered by your web site), you don't actually have control over everywhere that links to it. For example, Jane might have bookmarked your order form in her web browser, and Alicia might have linked directly to it on her web page about alternate media sources. You might not even know that she's done so, so you won't be able to make those changes. This makes it doubly important to choose the right name early on.

Other Resources

Last modified 6 years ago Last modified on Feb 2, 2013, 5:36:17 PM