Cleaning Up The Mess: How To Keep Your Coding Workflow Organized

Advertisement

Oops, we used the word “organized” in the title. Time to switch off — is probably what many would think. Being organized is a somewhat dull, though important, subject. Perhaps it would help to give it a bit of context.

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.

General Principles

Structure1
Structure is the essence to the project. Image by Chris Halderman2

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 code/users.php?

Don’t mix different aspects of your website. Keep modules of functionality separate, and keep different languages in separate files. I’ve recently helped out on a project where some poor, misguided programmer mixed CSS, ASP VB Script, JavaScript, HTML and SQL in a big jumble, all throughout a single, huge, poorly indented file. I’m not exaggerating. Enough said.

One Size Does Not Fit All

Brainstorm
Reflection prior to starting helps. Image by Andy Mangold3

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.

  • 1 page website
    Make a folder for images, a single file for CSS, another for JavaScript, another for content, and another single file for code. It’s definitely not worth separating template and content, unless you have specific requirements.
  • 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).
  • 20 pages website
    A folder for images, another folder for uploads and other business-related files (“assets”), another folder for content (or you might be using a database-based CMS by this stage). Your JavaScript, code, and stylesheets are probably getting complex enough by this stage to consider putting them in a separate folder. Name the folders something immediately obvious, e.g. css/, javascript/, code/.

    Make sure that all files go into their relevant folders. You shouldn’t have a stray .js file sitting, say, in the content/ folder, just because it’s convenient. If your templates or code don’t allow you to organize your files the way you need to, then do a quick code refactoring to make it work.

    Avoid putting CSS, templates, layout and design images, or JavaScript into assets/ (or uploads/ or 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.

  • 100 pages website
    You should be using a good CMS for your content by this stage. It doesn’t matter if it’s a database- or file-based CMS, but if it’s the latter, make sure the content files are well-organized, and make sure you can define metadata for individual page titles, descriptions, etc, or your SEO efforts will be very difficult.

    You’re probably also starting to have a number of different sections on your website by now. You’ll likely need to start factoring out the stylesheets, JavaScript, design images and templates into separate files and folders. Make sure these folders match each other, and match up with the sections of your website — or whatever makes most sense for your particular website. Using a CSS language like Sass4 or LESS105 is also a really good idea by this stage.

  • 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 curve6.

Your Client

Your client might have a wonderful shopfront, but is their kitchen organized? Talk about it!7

Communication with the client helps clear things up. Image by Andy Mangold8

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 logo/, reports/, competitive analysis/, etc. It also makes sense to put your design files in this folder, perhaps in design/ or graphics/.

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.

Images

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 images/.

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 form-warning-icon.png.

Stylesheets

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 main.css, or styles.css.

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 layout.css, content.css and forms.css. If you give them somewhat vague names like presentation.css, model.css, 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 Sass9 or LESS105 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 Turk11 for a job that computers do easily. You could use Minify12 (PHP) or Juicer13 (Ruby) for that.

JavaScript

Javascript code14

Image source: dmitry-baranovskiy on Flickr15

There’s a lot in common between organizing the JavaScript and CSS files for many websites. They both serve similar (but different) purposes, they’re both served up to the browser to interpret, they both interact with the DOM (when used appropriately), they often interact with each other. JavaScript is often used to add functionality to exactly the same set of elements that the CSS is used to style.

You’ll usually end up having your JavaScript library file (jquery.js, mootools.js etc.), a couple of widgets (say datepicker.js and dropdown.js), and some site-specific code (eg my-image-slider.js). It definitely makes sense to keep these in separate files, although you’ll often have so little site-specific JavaScript that it makes sense to just have one file for that part of it.

Put all these files into a folder named javascript/. Assuming you use a 3rd-party library like jQuery, you’ll very rarely build a site complex enough to sub-divide this folder any further.

Templates

Your templates are just skeletal outlines for your code to flesh out with content, and for your stylesheets to paint with beauty. Image source: dorena-wm on Flickr16

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

Assets

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 uploads/, resources/, files/, media/. Or you could break it up into separate main folders, called pictures/, 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 photos/, pdfs/, videos/ etc.

The Database

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 ORM17 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.

SQLite18 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 content/.

The Administration Section

Almost everyone puts the administrative files under admin/, when it’s needed. If you have an admin section, do the same. Don’t have duplicate code, images, JavaScript, etc. for the admin. Obviously, for the parts of the admin section that are different, you’ll need to have additional code etc. But it should be part of the same codebase, and factored such that you can use the helper functions from any part of the website.

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.

The Code

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 users.php.

Good factorization19 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.
  • 3rd-party libary code.

Use a version control system, such as SubVersion20. To learn about version control, take the time to read the guide to version control for web designers21.

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.

Keep your code well outside of any publicly-accessible folders. Do you really want everyone finding all the inevitable security holes in your code? Don’t mix HTML, CSS, or Javascript in with your server-side code, or vice-versa.

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.

bEat/
        website/
            images/
                boxes/ /* often still necessary for IE... */
                    red-bottom-left.png
                    red-bottom-right.png
                    red-top-left.png
                    red-top-right.png
                navigation/
                    navigation-sprite.png
                    background.png
                logo.png
                page-background.png
                twirly-list-dot.png
            css/
                layout.css
                content.css
                print.css
                mobile.css
            javascript/
                jquery.js
                datepicker.js
                site.js
            assets/
                pictures/
                videos/
                pdfs/
            templates/
                blog/
                emails-plaintext/
                emails-html/
                social/
                mobile/
                *.tpl
            content/
        code/
            *.php
        reports/
        graphics/

The same, in a shorter form:

bEat/
        website/
            images/
            css/
            javascript/
            assets/
            templates/
            content/
        code/

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 template22 (.zip), a skeletal PHP website, with a single content page, based upon the H2O template library.

Perhaps you like the following alternative better. It has the advantage of keeping everything for a single project inside a single project, at the cost of putting all the static files one level deeper. If you spend a lot of time working with CSS and JavaScript, that may be not so useful for you, but it’s a question of what’s important for your project and for your business.

bEat/
        website/
            static/         /* name it "public/" if you prefer */
                images/
                css/
                javascript/
                assets/
                content/
            templates/
            code/

Quick Recap

  • 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 images/navigation/*.png.
  • Avoid cluttering your filenames up with all sorts of extra prefixes and suffixes.
  • Managing your own time effectively23 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!

(vf)

↑ Back to topShare on Twitter

Bryan Hoyt is a web developer and designer based in the "tranquil" city of Christchurch, New Zealand. He's the lead web guy at a small, vibrant tech business called Brush Technology, providing web design, software development and electronics design to businesses and startups with innovative ideas. Outside of his job, Bryan has a passion for music, art, literature, and the outdoors.

  1. 1

    When working on websites, I structure my folders similarly. Another good idea that I use is setting up a “resources” folder for all your design files, like .PSDs, any .ai or .esp logo files. The setup that works best for me is to have a main Clients folder, with individual client project folders inside of that, and inside of there I have my resources folder, with all my design files, and then have my site folder with a similar structure to the one you’ve listed in the article.

    0
    • 2

      Yes, that’s a good idea. I use a folder called “graphics” at the top level of my client’s folder, for design files like that. It’s not project-specific, but that’s how I find my clients generally work out — a single logo, a single website, a few other brochures & business cards & things, but not enough to give them each their own project folder. Then I have the “website” folder, with CSS, exported images, code, etc, as it’s own project folder within the client folder.

      0
  2. 3

    One of the reasons I absolutely hate Dreamweaver is because it messes with my code indents. I use tabs to indent and I find time after time, seemingly random, that Dreamweaver will turn them into sets of 5 spaces. This pisses me off beyond belief. Does anyone know a solution to this?

    0
    • 4

      There is an option in your settings that either makes your indentation tabs or spaces. Just go for a little hunt for it, you’ll find it.

      0
  3. 5

    good article sir
    this stuff is very useful for beginner to start build website

    you explain clearly here
    thank you for this good article

    0
  4. 6

    Very useful for teaching newbie site creators. Cheers

    0
  5. 7

    I’m not sure I understand what a 100+ page website means… 100+ UNIQUE pages? Can’t be right?…

    0
    • 8

      Gabriel,

      Yes, that’s getting to be a largish site. But it’s not unlikely that a web developer will find themselves working on such a site.

      SmashingMagazine.com itself is well into the hundreds (thousands?) of unique pages.

      It does depend a bit on what you mean by “unique”. I mean “unique content”, not “unique layout”.

      0
  6. 9

    Anyone got any ideas on contructing and organising code librarys? ie a index of code snippets from javascript to php. I was thinking of putting my code library up on git, but right now its all over the place. Does anyone have any good ideas or tools that they use to organise their code library?

    0
    • 10

      madphp,

      Short answer: use your file manager + a good version control system. That’s all the tools you really need to organise your code. More tools can help, but also get you into trouble if you don’t have the basics sorted.

      First, make sure your library is all in one folder (divided into subfolders as necessary), and make sure there’s only one version of each file floating around your harddrive. Then, if you’re not using version control, start using it, and let that handle the different versions for you.

      Git, Bzr, Subversion, etc — all good choices for a version control system.

      Once you have all your source code organized nicely into a single folder and placed under version control, it’ll be a lot easier to put it up on a system such as Github, Google Code, Bitbucket, or a similar service.

      0
    • 11

      I’ve just started using Snippets (from Lucky Ants) myself. So far I like it very much. Right now, it seems to be on sale (probably in preparation for inclusion into the Mac App store). I like having my code in one app rather than in several documents all over my computer.

      0
    • 12

      The series, “Let’s Make a Framework” on The Daily JS blog is a great place to start:

      http://dailyjs.com/2010/02/18/framework/

      It talks about how to organize, structure, modularize and test a JavaScript framework.

      0
  7. 13

    Douglas Bonneville

    January 19, 2011 9:02 pm

    For simple sites that don’t need a folder to manage content, I have found that nice SEO names work well, and do double duty as file management helpers:

    financial-services.html
    financial-services-retirement.html
    financial-services-college.html
    leadership.html
    leadership-investment-team.html
    leadership-research.html
    investing.html
    investing-institutional.html
    investing-thought-leadership.html

    That way you don’t need folders to organize the content. You can’t go very far with this on a static site more than a glorified brochure, but limiting the use of folder makes updates and changes, if they are frequent, very easy.

    When you sort files in a directory, you get to see the “root” pages of your topics and its very, very easy to scan quickly by eye. The more scan-able, the better.

    0
    • 14

      Yeah, I’ve done things like that in the past too.

      Truth be told, though it’s convenient, I’ve usually regretted it — it clutters up your folders really quickly, and it’s not that hard to make a new folder (and it doesn’t hurt your SEO).

      I take your point about being scan-able, though. For that purpose, I usually just set my filemanager to show the portion of the tree that I need to see (not sure if it works in Windows Explorer — I use Nautilus).

      0
    • 15

      I’ve done the same and it usually depended on how many pages the website has. And though creating folders may allow for future expansions, I couldn’t stand having one to three files in folders within folders.

      Frankly, if the site did get much bigger then they oughta be on a CMS.

      0
  8. 16

    Great advice. I have a similar setup within a Dropbox folder, using Dropbox as a lazy man’s revision control system.

    Not recommended for large webapp projects but great for those small static sites.

    0
    • 17

      Yeah, Dropbox is pretty handy as a just-works hands-free system.

      I’m generally pretty sold on Subversion, but that’s because I’ve got it all set up. Bzr is another great option for version control, and easier to setup for a single user, though not as widely used. I’d definitely recommend something like Bzr for large websites with multiple developers, due to the decentralisation (which means each developer can commit changes locally before committing their changes to the production branch).

      0
      • 18

        1+ for using Dropbox and Subversion (SVN)! :)

        0
      • 19

        Your doing it wrong.

        Check out the Subversion Repo INTO your dropbox folder.

        That way it will follow you where ever you go and sync up your changes on all your machines (laptop, dekstop etc).

        Its great if you cant access your workplaces subversion server outside the building but you are allowed to use dropbox. You can work at home, your repo will auto sync over drop box at your workplace on monday morning then you can check it all in.

        :)

        0
  9. 20

    Patent Application

    January 20, 2011 12:26 am

    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.

    0
  10. 21

    Good stuff!
    In modern CMS’s like Drupal even when developing with modules a good structuring may help a lot. In more ‘raw’ frameworks like Django / Rails etc, this approach is even more natural.
    This article IMHO is more about planning than cleaning, which is more important of course because it eliminates the need to clean.

    0
  11. 22

    James Seymour-Lock

    January 20, 2011 1:46 am

    You should always have a folder which contains all the resources for the project, Such as any fonts used in the graphics or font-face, as 2 years down the line and you need to make changes to a graphic and cant find the font can be a real pain. Also a .txt file with the url’s to any stock photography used ready for when you have to buy it.

    Would also have a licences file, which contains all the licences for any fonts for third party scripts you are using.

    0
    • 23

      Very true — I tend to keep fonts either in “fonts/” or just in “graphics/”, if I use any non-standard fonts.

      Good point about keeping track of your stock photos — nothing worse than not being able to find a photo you’ve built your whole design around! I tend to just buy the photos I’m using as soon as I like the rough draft, at least for web designs — though for hi-res print work, that can start being a bit costly if you’re not going to use the design (that works for a site like iStockphoto which offers differently-priced resolution options)

      0
  12. 24

    We have our own version of WordPress which is focused on company website design with prepared functions, stylesheet “skeleton”, widgets, plugins, basic settings … We have it integrated in our server system, so when i set-up domain in our hosting, i click a button and everything is set-up.
    So for me – 1 page or 1000 page it does not differs – everything is the same (just then the complexity of settings).

    P.S.: similar approach we have for eshops

    0
    • 25

      1-click setup is an excellent idea, something for any web designer or company to work towards.

      I think that could start getting more complicated when you get into highly customised web applications. Each one tends to be quite different, require a different technology stack, etc. But even so, with great frameworks like Django, the technology stack is becoming much more consistent.

      0
  13. 26

    Bryan thanks for writing this article, I had a good laugh when you wrote about over organizing and being too abstracted, I’ve come across this far too often on other developers projects.

    Another stategy for media (images, video’s, etc) would be to use amazon’s S3, which is cheaper than most, arguably faster, and makes deploying applications a little easier as the application code is seperate. With your registrar you can change a long amazon S3 url to a short one using a cname record pointing to a subdomain, for example I keep my media in media.wavesummit.com

    One of the reasons I like Rails and why it is so popular, is the fact that there is a convention on where to put files, this means less configuration and rails developers know where to look for certain types of files. Like Django, Rails applications are very organised from the start.

    Thanks for the link to Juicer, can’t wait to try it out.

    0
    • 27

      Yes, we’ve used Amazon S3 in a couple of projects before for our static files. It’s faster if you live in the same country! Not any faster here in NZ, I’ve found.

      However, I wouldn’t recommend using S3 as your primary storage for the static files — even if that’s how they’re accessed over the web, you should definitely still work with the files in your version-controlled folder along with everything else. IMHO the only files that don’t have a place inside your version-control are auto-generated files (they don’t need tracking because they’re easy to re-generate, and as such you never need to edit them directly).

      Some VCS’s and workflows don’t support large binary files very well either, so that’s another special case. I tend to store large binary files in my personal working-copy, plus the production website, and make sure they’re backed up.

      Organisation is good, although I like the Python approach which treats each module or package as an independent piece of code which isn’t required to be in any particular place or have any particular naming convention — meaning your free to organise your own way. Django violates this a bit, which annoys me. Conventions are good, however — convention-over-configuration is one of the things which makes Django great.

      0
  14. 28

    I want as few files as possible in the document root of the website, so I lump everything for the frontend (images/css/javascript/uploads) into an assets folder, and then split it into separate folders for the different content.

    0
    • 29

      That’s not a bad approach. Your “assets/” folder is slightly different from mine (which is basically an “uploads/” folder) — I guess your “assets/” folder equates roughly to my “static/” folder.

      0
  15. 30

    Can anyone point me to a guide for using the template approach that is discussed in this article? Conceptually this approach really appeals to me, but I am not clear on exactly how to approach it.

    0
  16. 31

    Jason,

    Have a look at the basic template in the attached example folder: http://media.smashingmagazine.com/cdn_smash/wp-content/uploads/2011/01/sample-project.zip

    It’s in bEat/Website/templates/index.html and uses the H2O template language (based on Django’s template language — one of the best around).

    Then I suggest having a read of Django’s guide at http://docs.djangoproject.com/en/dev/topics/templates/ and Wikipedia’s article at http://en.wikipedia.org/wiki/Web_template

    There are other templating languages around. Smarty is a popular one for PHP, although it’s a bit big and ugly in my opinion: http://www.smarty.net/

    The lightest-weight PHP template language is PHP itself! But that requires a lot of discipline. See http://thephppro.com/articles/pte.php

    Twig is another PHP option. I really like the looks of it, but have never used it: http://www.twig-project.org/

    0
  17. 33

    I allways start with a new client folder .
    In this folder 3 new folders:
    COPY: for briefings, ftp and login data, for content text and pictures (subfolders)
    DESIGN: for all psd’s, ai’s,…
    PRODUCTION: for all website files with subfolders

    0
  18. 35

    I use an automatic folder creator (you configure your folder hierarchies any way you want) so that I can have consistently organized folders for each account across the board. It even recreates the documents you need within each folder. It’s working very nicely and takes the guess work out of organizing for each project.

    0
  19. 36

    I’ll usually do this structure under a project_name folder:

    _drafts
    _src
    _src/css
    _src/img
    _src/js
    _src/pdf
    _src/xml
    index.html

    I keep psd mockups under _drafts to easily find them, underscore moves _drafts and _src to the top for quick saving when slicing and dicing images. Of course this goes out the window when using an MVC framework.

    0
  20. 37

    Hi Bryan,

    Great article! Anyone who’s spent years doing large to huge scale websites development and maintenance – would agree: there’s no way around structuring your frontend codebase.

    I am in favour of a modular approach to developing front-end code, that way you can do encapsulation and reuse your codebase more easily across projects.

    I have recently published an Eclipse tools suite for managing modular HTML development, precisely aimed at structuring your frontend code:

    https://github.com/larjen/modulaise

    The install and tutorial should take you around an hour or so to complete. It is a bit rough around the edges, but the underlying principles have been battle-tested on development of large to huge complex websites.

    If you are going enterprise grade, have team members collaborating, hate to refactor everything from scratch and so on – this is one take at a solution. Feel free to have a looksie.

    /kind regards Lars

    0
  21. 38

    As I’m working on a site, I just know where everything is … the folder structure has been used in and out many times. It’s when I come back to a site after a period of time that trouble can be had if not for me effectively creating the necessary folder structure that I know. It’s my system so I know it better than anyone else. It has to make sense to others, too, for in a group effort they must be able to understand my system. And the system is much of what you’ve discussed above. I’ve gained some valuable tricks I’ll be using from this article. Thank you.

    0
  22. 39

    Good article. When I saw it in my RSS feed, though, I thought it was going to say, “Cleaning Up The Mess: How To Keep Your Computer running quickly.” *lol*

    0
  23. 40

    LOL:
    “100,000,000+ pages website
    You’re Microsoft. You should know what you’re doing by now.”

    As if!!!

    ……………………………………………………………..
    As if Microsoft knows what their doing…
    I recently read some teaching material for “microsoft certified network technicians” – half the TCP/IP stuff they teach is plainly wrong!
    ……………………………………………………………..
    There should be better examples around of companies who REALLY know what they’re doing, and don’t deliver bug ridden software, which you have to update with more bug ridden patches – until it’s time for a fresh install.

    0
    • 41

      ;-) I have to admit, I tend to agree. I was being rather tongue in cheek when I made that comment.

      That said, there are good reasons why Microsoft is one of the biggest software vendors in the world. They do some things right, and they do know a thing or two about software, even if they’ve made some pretty bad design decisions in the past. I think it’s useful to learn from the giants even if you don’t want to end up like them.

      0
  24. 42

    cool blog but folder structure also depends on project technology
    this can be extraordinary for php but for .net there are other ways and for java there can be others. So if you have “Big” projects and which is using server side technology then i would say it depends on project architecture.

    ie .net has files like .dll and files like .cs for c# code and under one solution there are different namespaces and under each namespaces there are different functionalities.

    so it always depends on customer, product requirements, technology and thats why architects are getting paid.

    but for small projects where there are less needs and cool things this is perfect ;)

    0
    • 43

      I agree, when your project becomes a large-scale application (as opposed to just a “website”) you start needing to think even harder about your filesystem architecture.

      However, I think the same principles apply — keep everything as simple as it can be (but no simpler); don’t over-engineer; keep related files in related places; keep different programming languages in different files (don’t mix), and keep your naming schemes short and clear — folders and namespaces are great for helping with this.

      0
  25. 44

    Sorry, disagree with the first point. If you have a code base with a lot of files (you suggest 100+), separating them into logical file system paths helps eliminate namespace collision and improve code logic. Do you think the way Zend Framework structures its files bad practice?

    0
    • 45

      Good point, Kevin. I guess I wasn’t trying to lay down any hard-and-fast rules, because it’s never 100% clear when you need to start “refactoring” your files & code into different files.

      Different people definitely do things in different ways, and different projects have different requirements.

      Just had a look at the Zend framework source code. It does look like a tidy and clear layout, although the folder hierarchy is a bit deep for my tastes. However, that’s often very necessary in a codebase of that size. However, Zend is a website/application framework, not a website, so it has hugely different requirements.

      In terms of how the Zend framework expects developers/designers to structure their own websites, I have to admit I haven’t used the Zend framework for a website before. However, my understanding is that Zend doesn’t place any restrictions on how you structure your code and files — which is a good thing, in my opinion: don’t hold developers’ hands.

      0
  26. 46

    Nice Stuff Sir,
    It’s is very useful for everyone to start developing websites.

    In today’s CMS’s like Joomla, Magento, Drupal even when developing with modules well organizing may help a lot.

    Thanks for this great article

    Er. Dinesh Saini
    WebMaster
    Vision Shine Infotech (www.visionshine.com)
    Rohtak

    0
  27. 48

    I abandoned your article, after reading the first paragraph. WIth an article titled ‘coding’ you told me I was a designer. Which I’m not.

    0
    • 49

      Sorry, David — I didn’t intend to lead you down the wrong track.

      The article was definitely intended for coders, but especially fledgeling coders who haven’t had much experience with more complex websites, and there are a lot of designers who are also fledgeling coders. In fact, there are a few (experienced) coders who still write nightmare code, so I was hoping to catch a few of them, too ;-)

      Sounds like you’re pretty switched on, so you probably made the right decision.

      0
  28. 50

    This is a great article! I can tell from experience that this is something that has to be properly carried out, or else you will have troubles down the way!

    I’d like to see more of those, but a bit more advanced.
    The thing I am most interested in right now is how to deploy code/applications ?

    And by deploying I mean a few things:
    - you have multiply uncompressed css files and you work on them, but once you push/copy the code you would like them to be all compressed and inside one file,
    - same for JS
    - let’s say you have to put different versions of your code into separate folders
    - lots of other thins you would like to be AUTOMATIC

    Does anyone know a tutorial or a post on this topic ? Like how to write your own scripts that would do this stuff ? For example some advanced Git Hooks (Python :D) ?

    Have a great day.

    0
  29. 52

    Nothing scares me more than getting a call or email and hearing or reading, “our wed designer quit …. can you finish this project?”

    I’ve never gotten into another person’s code and found good structure. I don’t think it exists. It’s a myth. Stop teasing me.

    0
    • 53

      That’s because the developers with their act together from a structural standpoint finished the job and moved on to the next one.

      You’re tasting half-eaten discarded sandwiches and saying there are no good sandwiches…

      0
    • 54

      Shiver me tbeimrs, them’s some great information.

      0
  30. 55

    Everyone/Company has their own preferred layout and theres nothing to say they’re wrong; in a lot of instances its also driven by architecture and the language being used (Ruby/.NET/etal) as these can pre-define the structure of your site.
    The only thing I’d query really is the part about using something like LessCSS as a site gets to 200K pages, not really the most relevant.

    Its good to see these ideas floated, but its definitely an item of design/dev that boils down to personal preference.

    0
    • 56

      Yes, it does boil down to preference in a big way — but like with any aspect of design (yes software is designed too, just like graphics!), although it’s subjective, there are still bad approaches to avoid, and good approaches to follow.

      I’d agree, don’t take these ideas on board if they don’t suit you or your type of project. But I think the general principles still apply in most cases (and, as with any good rule, there are exceptions, but use them wisely).

      Good point that Sass/Less don’t really have much to do with the size of your site. However, I’ve found that often, as a site grows in size, the amount of CSS needed also grows, and Sass/Less will really help to manage that growth. Like you suggest, though, that’s not always the case.

      0
  31. 57

    For anyone who’s interested, there’s a Chinese version of this article available here: http://nightknight.blog.com/2011/01/23/cleaning-up-the-mess-how-to-keep-your-coding-workflow-organized/

    Thanks to Night Knight for the translation!

    0
  32. 58

    I’d just like to clear something up. I’m probably being a complete newb and not thinking it through, but if you’re using a CMS why would you need a Code folder? The CMS will already contain all the code you need and I’d imagine any changes to code or plugins/extensions you make would reside in that folder – as well as your themes?

    Perhaps that is the case and I’m just getting confused down to my own personal preference.

    For me personally, I keep the latest copy of WordPress downloaded and extracted on my hard drive. I then have my folders structured as follows:

    Project -

    _Site Backups
    _Ad Campaigns (I run Google Adwords for my company too)
    _Website Files -
    Image Files (PSDs etc) -
    *Work Files
    *Final Copies
    Theme (contains the php) -
    *CSS
    *JS
    _Site Pictures
    _Documents

    I don’t use Subversion, I’ve only recently discovered it so until I have gotten to grips with it I’m sticking to regularly backing up the website and giving each backup a version and a date, e.g. 29/12/10 version 1.0.3. The most recent backup is always the site as it is, i.e. basically a duplicate of what’s in the Website Files folder.

    I’m not terribly well organised…but it works for me, if I need to upload something I always know where to go.

    0
    • 59

      What you do looks fine. I’m very glad you’ve discovered version control — you’ll never go back, once you’ve learnt the basics.

      You’re right, if you’re using a CMS, you typically won’t need a code folder. But if your website wants to add extra functionality to the CMS, or if you have other modules besides the CMS, then that code will need somewhere to live, and it should generally be separate from your content, templates, css, javascript, images, and other files.

      0
  33. 60

    Your “views” (as Django calls them). These are “controllers” in MVC language. Briefly, a “view” is any code specific to a particular URL.

    Really? Clearly, you haven’t done any webapp using the MVC architecture, ayt?

    0

↑ Back to top