While reading Microsoft’s 7 Tips for Team Web Sites it occurred to me that we don’t have a firm set of file naming guidelines. So I looked around for and compiled a list of techniques that we currently use and those that we should be using.
Backwords naming - If we have a file that will be used as an include, and displays a user account, we will call it “accountDisplay.” Why do that, when it makes more sense to say, “displayAccount?” The reason is so that we can arrange files alphabetically, and find all files that deal with an “account” bundled together.
Don’t use underscores - We prefer to use the “-” character rather than the “_” character. There are a couple of reasons for this. First, an underscore requires the use of the shift key, which is a minor inconvenience. Second, when sending a link to someone underscores blend in with the link underline.
Dates - When handling periodicals, Bob Hoffman tells us to keep dates in mind in Naming Conventions. Basically, use a numerical naming system so that the issues appear in date order, rather than in alphabetical order.
Avoid Redundancy - An interesting bullet point in Naming Files and Directories brought a new idea to my attention. When naming your files, do not make them state what has already been said. So, if you have a folder named “features”, a file inside should be called “weekly” rather than “weeklyFeature”. It is a given that it is a feature because it is in the “features” folder.
Lowercase - Many articles suggest to use an all lowercase naming scheme. While this seems obvious enough, it just passed me by. When I am programming, I prefer to name functions and variables with a lowercase/uppercase scheme. For example, a function name could be
addUserToDatabase(). Without even thinking about it, I did the same for my files. I would create “addUser.php.” Even though no user will ever have to type in that file, it is best to be consistent.
For more information, check out Dey Alexander’s article on General File Naming Tips and Net Mechanic’s file naming and search engines. Both articles are a bit dated, but still provide some rather useful information. Are there any “must-do” techniques that I am missing?
The “weeklyFeature” instean of just “feature” is mostly used due to editor limitations. When the tabs only display the filenames, and you have feature/weekly, dates/weekly, and tips/weekly, you have a hard time.
I do not buy your first objection against the underscore. It does need the shift key, so does using uppercase letters as in your final point.
I also do not quite buy your argument about the underscore blending into the link underline. The link is still clickable, and one cut & pastes the linktext and does not transscribe it.
A point against hyphens in filenames might be broken mailclients which break lines on hyphens, if you send the links as plain text.
I just reread my post and I phrased the last point in a confusing manner. I actually am in favor of lowercase, and against uppercase. I was giving an example of how I incorrectly use uppercase based on my programming habits. Sorry for the confusion - I’ll update the post.
As far as underscores go, there are plenty of arguments for and against them. We just happen to be against them. I wouldn’t say it is wrong to use them, we just prefer not to.
I agree with your point against weeklyFeature. Your example would become confusing.
I’m totally against increasing your pool of letters by using uppercase. It makes it nearly impossible to guess the name of a function when you know its purpose. There is not argument for this that is reasonable and I can’t understand why people advocate it and in some cases suggest it to be the only way. ( I know you are not saying it is the right way I’m just venting)
Also another tip to naming files is to have a prefix for files that are associated to each other by entity.
post-add.php post-edit.php post-view.php post-search.php
Again no uppercase and with this convention you always know were to look. Also entities should always be singular. So ‘post’ as opposed to ‘posts’. This also applies to database naming convention.
I actually use underscore instead of hyphen but I take your point about the shit key and might write it into our code guidelines although i don’t think it makes much of a difference. The random uppercase letters does get on my nerves though.
I agree with your “post-add”, “post-view” example. That is what I was trying to get across in my first point, but I screwed up and used the capital letters again. It’s a bad habit I have to break.
As far as coding goes, I’m still not against capital letters. I would prefer
addEmployee()toaddemployee()oradd_employee(). I’m interested to hear your take on this though.Backwards naming. I shall begin to use it right away. Thanks!
The common term for the “lowercase/uppercase scheme” you use for function and variable names is “CamelCase”. I’m guessing you may have known that, but avoided using the term so as not to confuse the uninitiated.
Cheers!
http://en.wikipedia.org/wiki/CamelCase
I was actually unaware of that. Thanks for pointing it out.
In writing, they’re also known as intercaps, incaps, midcaps and BiCaps. But I think in referene to programming, they’re just CamelCase.
When you use numbers for dates, use yyyymmdd format, so that the filenames will sort next to each other. Then you can find the code you worked on last Spring fairly easily. Or last year. If you do it as mmddyyyy, all of your September articles will be next to each other.
Everyone needs a hug.