Changes between Initial Version and Version 1 of faq/files/choosing-names

Nov 1, 2007, 7:46:07 PM (13 years ago)
Daniel Kahn Gillmor



  • faq/files/choosing-names

    v1 v1  
     2= How should i choose the names for files in my web site? =
     4As 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.
     6== good characters ==
     8It'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 (.).
     10Avoid 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 `` 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.
     12It would be better to call the file `colorbrochure.pdf` or `color-brochure.pdf`.
     14== specific names ==
     16When 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.
     18== versioned names ==
     20Say 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`?")
     22In 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.
     24So 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).
     26== durability of names ==
     28Note 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.
     30== links ==
     32 * [ Cool URIs Don't Change] by Tim Berners-Lee talks about choosing good, permanent names for resources on the 'net
     33 * [ RFC 1738: the technical definition of URLs] -- see section 2.2 about character encoding issues.