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

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

Structure-main in Cleaning Up The Mess: How To Keep Your Coding Workflow Organized
Structure is the essence to the project. Image by Chris Halderman

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.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: