How To Keep Your Coding Workflow Organized
Let’s keep it classy, and imagine we’re building a website for a trendy restaurant/café called “bEat”, catering to the arts community. It’s an atmospheric place with 1920’s art on its interior brick walls, live jazz, and rich patrons. But they don’t have a great website, so they’ve called you in to save the day. As a talented designer, you’re confident you’ll be able to pull a fantastic design together that they’ll love, but they’ve got a lot of clever ideas about the website’s functionality, and you’re not quite so confident about how to organize all the files that your website will need.
They need to be able to edit content themselves, upload pictures for their weekly blog posts and new content. Pretty normal so far. They also need to hook in with Twitter, so their blog posts are automatically tweeted. They need a mobile app for iPhone and Android, because their customers are using a smartphone, and they want to offer specials & menus direct to their smartphones. Down the track, they’d like to have reviews submitted by their customers, with possible pictures, links, etc. Lots of cool interactive social networky stuff, friends, online user-submitted video.
‘Facebook for restaurants’ they say, by way of making it easier for you to get your head around. Ok, by that stage, you’d probably tell them to go waste someone else’s time. But you get the idea.
Perhaps in the past you’ve tried to build a more complex, cutting-edge website like this, and the project started off with great enthusiasm, but ended up in a nightmarish mess that you couldn’t maintain. Your client lost interest when new features started getting too hard to add, and you started having to work late at night, tracking down bugs that you couldn’t even find the relevant file for.
After a project like that, it’s not hard to see the relevance of a well-organized website project.
Keep everything simple and clear. Don’t over-organize — some websites & frameworks out there seem to have a masochistic need to make everything a theoretically perfect abstraction. In practical terms, that usually means it’s impossible to work with.
If you start creating tens (or hundreds) of tiny files, each containing nothing more than a small class or function, you’re definitely overdoing it. If your files and folders have names that are too abstract or generic, then things are probably starting to get a bit silly. For example, if the code to check the login for a website administrator is stored in a file called
WebsiteData/Items/GenericUser/AdminUser/Code/Auth.php then you’ve committed both sins. Why not just a function called
check_login() in the file
One Size Does Not Fit All
The depth of your folder hierarchy and the number of individual files should make sense for the size of the website. Keep it in perspective.
Here’s a quick list of some typical approximate website sizes, and how you might structure things accordingly.
- 5 pages website. A folder for images, one file for CSS, JS, code. Consider putting your content files in a separate folder. Again, not much need for templates here, usually. By this stage, make sure you have a template for the header and footer of your page (and any other common elements on all the pages).
code/.Make sure that all files go into their relevant folders. You shouldn’t have a stray .js file sitting, say, in the
resources/, depending on what you call it). These files are effectively code that your client should never have to think about, and the
assets/folder is for business-related files and media. Make it a golden rule for your workflow and stick to it.
- 20 pages web application. Much as above, but by this stage you should definitely be putting all your code in a separate folder. Make sure it’s not inside a folder where Apache might accidentally serve up the plain files when some script-kiddie has a tinker.
- 2,500+ pages website. You should definitely think about hiring some people dedicated to certain aspects of the website, such as a content editor, designer, programmer and SEO expert. You’ll also want your content to be in a database-based CMS by this stage, if it’s not already. You’ll start being the manager, and having the bulk of the work done by other people. Make sure you have smooth-running systems in place to allow you to review their work, and edit it before it goes live.
- 100,000,000+ pages website. You’re Microsoft. You should know what you’re doing by now.
Most small websites very quickly grow to over 20 pages, if they’re being actively maintained — by the time you’ve added a couple FAQ pages, a few little tidbits of content to explain something in more depth, and a product or two, it adds up quickly.
In that light, consider making all your small websites structured like an (approximately) 20-page website, unless you know the project is a quick, one-off website, such as an information site for an upcoming event, or a page for your wife’s birthday. Plan for growth, but don’t plan for a hockey-stick growth curve.
You should have a folder for each customer, unrelated to the actual project you’re working on for them. Inside this folder, you’ll have a folder for each project. Initially, there’ll just be a folder called
website/, but before long, you might have other folders called
competitive analysis/, etc. It also makes sense to put your design files in this folder, perhaps in
Don’t make this folder accessible by Apache. It will contain sensitive information.
Depending on the framework you use, you might like to put the code in this folder, to keep it outside of your website folder. You could call it
code/, or, if you think there’ll be separate code for other projects,
website-code/. If most of your other projects are design or business-related, then they probably won’t have any code, other than the odd script which wouldn’t need a separate folder.
In addition to the customer’s work folder, you might like to have a completely separate folder for documents that you don’t want your customer to see. You might find yourself regularly sharing work-related documents with your customer, and it’s quite likely that at some point you’ll want to give them access to their whole folder (and some customers will ask for it: “Can you zip up all my files and send them through? I just want to make sure I have a copy of everything”). Rather than risk accidentally sending them the file “10 things I hate about these guys.doc”, put it in your customer’s private folder.
To recap quickly, here’s an example of structure we’re currently looking at:
YourBusiness/ Accounts/ Documents/ Customers/ bEat/ Minutes/ 10 things I hate about these guys.doc Proposal.doc CustomerProjects/ bEat/ website/ ... this is the bit we’ll be discussing .... code/ ... and this ... reports/ graphics/
So, What’s In A Website Like This?
From here on in, we’re talking about the “code/” and “website/” folders listed above.
There are (almost always) two sorts of images: those that are part of the design, and those that are part of the content provided on the website. The latter should go into your assets (or uploads or media) folder, perhaps in a
pictures/ subdirectory. For design images, you’ll rarely need to stray from the beaten path: put them all inside
If your design is a little more complex, you might have images for buttons, icons, navigation, page background, etc. In that case, you’ll quickly get above 10 or 20 images in this folder, so consider breaking it up into subfolders. It’s still fine to have general-purpose images in the top-level, but the subfolders will help to keep control of all your zillions of little files. Name the files sensible, easy-to-remember names like
For most sites, your stylesheets don’t need to get very large. For a small site, or even a larger site, without many different sections (each with a different design), you’ll often get away with only one file for your CSS. If this is the case, just name it
Even so, a lot of people like to break their stylesheets up into multiple files. There are different ways to do this. A popular option is one stylesheet for layout, another for typography, another for colors. This is a nice idea, but it gets tricky to manage in practice — you end up defining many of your classes 3 (or more) times, and tracking down bugs can be a nightmare.
I believe a better option is to separate out “layout” and “content” styles. “Layout” includes things like navigation, header & footer, sidebars, boxes, sections. “Content” includes things like paragraphs, headings, blockquotes, lists, floating images, links. If you carry this a bit further, it also makes sense to have a file for “forms” styles. However, as content on the web becomes much more interactive, the line between forms and content (no pun intended!) is quickly being blurred.
Again, call a spade a spade, and name these files
forms.css. If you give them somewhat vague names like
page.css, you’ll always have to think first before deciding what file to look in.
Sometimes it’s useful to have an individual CSS file for special pages that have their own design requirements. This can be more trouble than it’s worth, depending on the complexity of the page. If you find yourself flicking between tabs in your editor, trying to find the right CSS file for a particular element, then it might be better to simplify your CSS. Also, seriously consider using Sass or LESS to make your CSS much more beautiful and clean.
You probably also will have separate stylesheets for different media, and these absolutely need to go in separate files. As usual, name them something sensible, like print.css.
If you have multiple CSS files, that’s great, but make sure you use an automated tool to merge them all into one file before serving them up, or your website’s download speed will suffer. Don’t merge your beautifully factored CSS by hand. That’s using a Mechanical Turk for a job that computers do easily. You could use Minify (PHP) or Juicer (Ruby) for that.
mootools.js etc.), a couple of widgets (say
dropdown.js), and some site-specific code (eg
Put all these files into a folder named
Templates are not content, are not code, and are not presentation. Templates can have certain aspects of all those things, but only the barest hint, when used properly. It might help to think of your templates as skeletons. Your server-side code fleshes out these templates with content (content from the database, error messages, form-field values, etc), and the browser applies an aesthetic skin to acheive the end result.
Of course, your templates might have the odd piece of human-readable text, for a button, dropdown, or whatever. That’s fine — that sort of text tends to be closely associated with the function of the page, rather than the content.
Put the templates in a
templates/ folder. In spite of what I said above, templates are really server-side code (they’re sensitive), so make sure they’re not publicly accessible.
If your website sends out emails, then have a couple of subfolders in this folder for plain-text and HTML email templates. If your website is more than just a brochure website, you’ll need many templates, for the different pages and screens of your application. If you have a smartphone version of your site, have a subfolder for it. Structure these subfolders appropriately. Here’s a good example:
templates/ blog/ sidebar.tpl post.tpl comment.tpl emails-plaintext/ subscribe.tpl change-password.tpl emails-html/ subscribe.tpl change-password.tpl social/ twitter-feed.tpl facebook-sidebar.tpl mobile/ base.tpl contact.tpl customer-profile.tpl friend.tpl homepage.tpl reviews.tpl base.tpl contact.tpl customer-profile.tpl friend.tpl homepage.tpl reviews.tpl
This is a name I really don’t like, though the alternatives aren’t necessarily much better. This is the folder where you put all the audio, video, documents, pictures, and anything other non-textual (or non-HTML), usually business-specific, content, which you want to be publicly available on your website.
Some alternatives for names are
media/. Or you could break it up into separate main folders, called
audio/ etc — but that gets messy pretty quickly. However, it is often good to have sub-folders for different types of file.
I tend to use
resources/, personally, but it’s a bit abstract. Not a very good name, though better than
assets/ (what are we, accountants?). However,
assets/ is almost an industry standard, and if I were to start fresh, that’s probably what I’d use. So for the sake of this article, lets go with that.
If this is just a small business website without massive content management concerns, then the security of these documents isn’t a concern. If it is, then you should have those sensitive documents in a completely different folder.
If you have a larger-scale website with needs for permissions-based access to different available content, then you should use a document management system of some sort.
In light of that, it’s perfectly safe to make this folder publicly accessible from your website. Your client should be able to upload items to this folder themselves, and link to the items via the CMS.
If you don’t have many non-web documents, then there’s no point in sub-dividing this folder any further. However, if you have a lot of these files, it makes sense to have subfolders with names like
This article isn’t really about database design, so we won’t deal with this much here. But it is important to keep your database well-structured. You’d do well to use an ORM in almost every situation — very few websites have unusual enough data requirements to need anything an ORM can’t acheive. Any good ORM can acheive virtually anything the underlying database can, anyway.
SQLite is a great option for most websites, because it’s easy to deploy, exists as a simple file on your file system (but is a full-featured relational database), and it’s simple to backup (no fancy import/export, unless you want to — just use a standard file backup solution. Of course you already have one, right?)
Name your database the same as you’ve named your project folder. Don’t have a separate database for each aspect of your website, but do have a separate database for each website you develop. As always, keep it simple, use short, full words as names, and don’t clutter things up with all sorts of extra prefixes and suffixes.
The Content Management System
These babies generally take care of organizing themselves. But do use a CMS that’s decently structured and well-coded. If you use a file-based CMS, put all of its content in a subdirectory, say
The Administration Section
Almost everyone puts the administrative files under
Food for thought: you may not need an admin section at all. For example, if your client needs to upload and edit photos, why not provide an “edit” link right there next to the photo? Similarly for posts, comments, etc. Of course, be sure that you still have robust authorization and authentication.
Whew. Where do I start? Software development is a complete field of knowledge in itself, and software is among the hardest things in the known universe to keep organized. I won’t even begin to cover all the ground here.
However, the rules stay the same: don’t hide files deep inside a hierarchy if possible, name your files using short, concrete nouns. Do use subfolders when necessary — but for most websites you shouldn’t have that much code. Stay on top of it. Make sure you use the same names for the same things — if you’ve called the database table
users, don’t name the relevant file
members.php. Name it
Good factorization is by far the most important aspect of keeping software organized, and it covers all levels of your code — from the folders right down to the names you choose for your variables. It’s is the single biggest deciding factor that separates competent programmers from the inexperienced ones. Go learn all about it.
Some things to keep in their own separate files and folders:
- Your data model. If you have a lot of logic attached to each type of object, you’ll probably want to have a separate file for each major class.
- Your “views” (as Django calls them). These are “controllers” in MVC language. Briefly, a “view” is any code specific to a particular URL.
- General-purpose classes and functions.
- Your library code. This should probably not even be inside your project or client’s folder — you should have a system-wide collection of library code you use, so you don’t have to manage multiple copies of the same thing.
- Third-party library code.
Use a version control system, such as SubVersion. To learn about version control, take the time to read the guide to version control for web designers.
The files here will often have corresponding files in your templates folder, although there won’t always be a one-to-one match. Where there is, though, use the same name for both files.
The Final Folder Layout
Of course, you should consider the given situation to determine what’s best for the project. The example below is by no means complete, and exists solely to give you an idea of what we’ve discussed.
The same, in a shorter form:
Admittedly, it looks pretty basic, when you reduce it to that. But the fallout from getting it wrong can cost a lot of time and effort. You can download the sample project folder template (.zip), a skeletal PHP website, with a single content page, based upon the H2O template library.
- Keep it tidy. Don’t drive everyone insane with your need to have a perfect folder layout, but avoid putting files in convenient but incorrect locations.
- Use sensible filenames. Concrete words that bring up a (relevant) picture in your mind’s eye are best. Where possible, use single words to name your files, but not at all costs.
- Often (but by no means always) when you need to use two words to name a file uniquely, it’s a sign that you should make a subfolder. Instead of
images/navigation-*.png, you might be better off with
- Avoid cluttering your filenames up with all sorts of extra prefixes and suffixes.
- Managing your own time effectively will help you find time to organize your website files — remember, quadrant 2!
Of course, we’re not perfect, and the suggestions here are definitely not the only (or best) way to do things. How do you organize your own website files? Let us know in the comments!
- A Simple Workflow From Development To Deployment
- Powerful Workflow Tips, Tools And Tricks For Web Designers
- Improving Code Readability With CSS Styleguides