Naming conventions

For use in Jon Ippolito's projects and classes.

Version 2.0
Modified by Jon to add namespace.

Purpose

For ease of understanding annotation

To isolate name space (dot, this, etc)

Facilitate remembering filenames

Facilitate sorting

Facilitate posting online

Facilitate cross-platform

Principles

Preserve only one master

Terms

Include your name for individual homework assignments.

When naming files to give to the instructor, include your name and some indication of the assignment. Remember that your instructor will receive a dozen or more files of the same exact format on the same day; make it easy for her to find yours.
Good

johnson_freud_essay.doc

gonzalez_javascript.html

gagne_promotion.mov

Bad

My Homework

Capstone Essay

Movie.mov

Avoid trigger words in file, variable, and function names.

Reserved words
Bad

window

document

body

html

Good

my_window

gallery_window

Words that could be blocked by browser software
Bad

ad

advertisement

banner

Good

logo

heading

Declare a namespace object and make all variables properties of that.

gallery = new Object() ;

gallery.name = "My Gallery" ;

gallery.imageLimitInt = 12 ;

Avoid unintended double entendres in domain names, which aren't capitalized in a browser.

Real examples
Tech advice

ExpertsExchange.com or ExpertSexChange.com?

Agents for performers

WhoRepresents.com or WhorePresents.com?

Counselling

TherapistFinder.com or TheRapistFinder.com?

Travel

ChooseSpain.com or ChoosesPain.com?

Skiing

GoTahoe.com or GotAHoe.com?

Pen store

PenIsland.net or PenisLand.net?

"Whether you’re looking for a long and skinny pen, a thick pen, a fountain pen that squirts ink, or even a black pen, we have just the one for you."

More examples
http://domainrookie.com/hilarious-domain-name-mispronouncings

Typography

Avoid weird characters

No spaces
Only - and _ are standard across platforms; @ and () can sometimes be used in urls.

Use case consistently

In HTML
All lower-case

Compatible future standards like XML

Good: <a href="http://yahoo.com">

Bad: <A HREF="http://yahoo.com">

In url pathnames
Run-together style

myprojectmenu.html

Sometimes used in url pathnames

Illegible for phrases longer than 2-3 words

Lower case and underscore style

my_project_menu.html

Facilitates selection of individual words

Best for url pathnames

Won't work for CSS names

In PHP names
Underscore style

get_my_data

In CSS names
Hyphen style

my-headline-style

Works cross browser.

In JavaScript names
Capitalization style

myProjectMenu

Only capitalize the first letter if the name refers to an object

Hard to remember for url pathnames

Abbreviation

Fixed number of characters

Choose a set number of letters so you can remember.
Good

Alabam

Alaska

Arkans

Bad

Alabam

Alaska

Ark

Start from beginning

Bad: "Gallerist" -> Gllrst
Hard to search
Hard to sort
Good: "Gallerist" -> Galleri

Don't skip a letter until necessary; when necessary, skip only as many as you need to.

If first you abbreviate "Galleri[es]" to Galleri
Then next abbreviate "Galleri[st]" to Gallers

Versioning

If a document will have multiple drafts or versions, use numbers

Bad: words that imply finality
"new", "latest", or "final"
Good: version numbers
Decimal digit indicates incremental upgrades

project_menu_v01.0.html (first draft)

project_menu_v01.1.html (fixed minor bugs)

Whole number indicates significant modifications

project_menu_v01.0.html (first draft)

project_menu_v02.0.html (rewrote in Flash)

You can run letters into numbers, but not vice versa; and don't start with a weird character

If you must break a document into multiple parts, distinguish them by letters

Bad
my_speech1.txt (first part)
my_speech2.txt (second part)
Good
my_speech_a.txt (first part)
my_speech_b.txt (second part)

Extensions

Use three-letter, lower-case extensions

Good
.jpg
Bad
.jpeg
.JPEG
[none]
Exception
.html

some servers default to this over .htm

Directory structure

Self-contained site

ROOT
|_ tech
|_ my_javascript.js
|_ my_styles.css
|_ media
|_ my_flash.swf
|_ my_flash.fla
|_ my_image.jpg
|_ my_image.psd
|_ my_sound.wav
|_ data
|_ my_database.txt
|_ index.html
|_ second_page.html
|_ third_page.html

Site with re-purposed content (eg, styles). Use ..\ convention to link HTML files back to tech and media files

ROOT
|_ tech
|_ global_javascript.js
|_ global_styles.css
|_ media
|_ global_flash.swf
|_ global_flash.fla
|_ global_image.jpg
|_ global_image.psd
|_ global_sound.wav
|_ data
|_ global_database.txt
|_ my_first_project
|_ tech
|_ local_styles.css
|_ media
|_ local_image.jpg
|_ index.html
|_ second_page.html
|_ third_page.html
|_ my_second_project
|_ tech
|_ local_styles.css
|_ media
|_ local_image.jpg
|_ index.html
|_ second_page.html
|_ third_page.html
|_ my_third_project
|_ tech
|_ local_styles.css
|_ media
|_ local_image.jpg
|_ index.html
|_ second_page.html
|_ third_page.html

Publishing

For a single file, keep the latest numbers, then when you need to "publish" the latest version, save the latest version without a number.

index_v01.7.html -> index.html

For linked files, you have two options:

OPTION A: Don't number individual files, but do number the folder they sit in. In this case you have to copy over all files from previous versions to each new folder, whether they were modified recently or not:
my_first_project
|_ my_first_project_v01.0
|_ index.html
|_ second_page.html
|_ third_page.html
|_ my_first_project_v01.1
|_ index.html
|_ second_page.html
|_ third_page.html
OPTION B: Keep all files in the working directory without numbers, but save a numbered copy of each in a versions folder. Applications like BBEdit can facilitate this using the Backup Now command.
my_first_project
|_ index.html
|_ second_page.html
|_ third_page.html
|_ archive
|_ index_v01.0.html
|_ index_v01.1.html
|_ index_v01.2.html
|_ second_page_v01.0.html
|_ third_page_v01.0.html

Write the version number into a comment in the beginning of the document itself.

If you later publish documents without version numbers in their filenames, this will help you sort out their versions.
Include the name of the last reviser and what they revised.
HTML version comment
<!- My Project Page version 1.2 -->
<!- Modified by Jon to update image links. -->
CSS version comment
/* My Project Styles version 1.2 */
/* Modified by Jon to improve link visibility. */
JavaScript version comment
// My Project Script version 1.2
// Modified by Jon to fix bug in pull-down menu.