Code Organization – its not just for Rails anymore

Photo by allyaubryphotography

I read an interesting article this morning on A List Apart on how to setup JavaScript to mimic the traditional MVC (model, view, controller) framework model of various server-side frameworks such as Ruby on Rails and CakePHP. This got me thinking about how important structure is for the current and future development of a project, all the way down to its interaction scripting. Without clear structure, everything is gnostic to its original developer, making it extremely difficult, if not confusing, to collaborate with other developers.

Here at dt we often collaborate with development partners to bring to life designs we have created for a client. Our core competencies in the dt offices are focused (although, by no means are they limited to) on the User Experience (UX) and User Interaction (UI) area of code. For this reason we will often only deliver valid XHTML, CSS and JavaScript libraries for interaction to our development partner (whether that is our primary recommended partner or the client’s development team). This is a critical phase in the project that must happen smoothly, so creating clear code and integrations are important. Read on for some of the principals that we follow to help make things run smoothly…

Well organized and structured markup
Keep your markup organized and concise for easy understanding. Classes and IDs on elements should be used where needed and should be descriptive. This hooks and explains your markup very well providing a lot of flexibility for future enhancement. Use classes for generic and common definitions and IDs for elements which will need specific definition overrides. Couple this with semantic markup and it should be very easy to understand exactly what element is doing what.

Commented and sectioned CSS
Section out your CSS with comments indicating page specific sections of style definitions. Place all generic class and tag level umbrella styles in a section at the top of the CSS file for easy access to styles that define the base presentation of the site. If you are planning on integrating into an MVC library such as CakePHP or Ruby on Rails and you have a lot of very custom styles for complex layouts, you may even want to create a base application.css that contains site-wide definitions and individual controller named CSS files to couple with each controller.

Un-obtrusive and Object Oriented JavaScript
Un-obtrusive JavaScript is your friend when writing front-end code. Nothing should exist in the markup that isn’t markup. This makes it very easy to take an XHTML/CSS/JavaScript based prototype of a user interaction to integrate into a back-end system as no in-line JavaScript needs to be transposed, duplicated or incorporated into a view.

Making the JavaScript you write Object Oriented also helps with implementation for a few obvious reasons. This keeps the window namespace un-cluttered, your code structured and organized, and if you are deploying your JavaScript in individual library files it is very easy to deploy a patch or upgrade by replacing the library file. If you are not familiar with writing JavaScript in an Object Oriented manner, check out Mozilla’s Developer documentation or 3 ways to define a JavaScript class. Understanding how to write Object Oriented JavaScript code is critical in writing MVC based script like that in the previously mentioned A List Apart article.

DRY JavaScript
Those of you familiar with Ruby on Rails should already be familiar with the term DRY – Don’t Repeat Yourself. A good rule of thumb to follow is if anything is going to be referenced or typed more than once, define it as a variable or make it into a function that you can then just call. This makes it extremely simple to do updates and reduces the chance of your code breaking. In JavaScript a good practice is to define an object or array of CSS class names, CSS ids and common values used in formulas at the top of your Class for easy access.

Hand-off documentation
Once you’ve written all of your code and area ready to hand off to other developers, be sure and write up a hand-off document. I recommend going as granular as line based implementation instructions as you cannot always be guaranteed that the RoR or PHP developer you’re handing your scripts to knows JavaScript as well as you do. If you’ve done your job right and kept things DRY, un-obtrusive and Object Oriented/Class based, this should be a very short doc merely specifying AJAX URL paths that need referencing.

These are all some great suggestions for working with multiple developers, but it also helps if you’re working solo as a free-lancer. Its never fun trying to interpret your own code that you wrote in a flurry a few months back. Organization, commenting and consistency help a ton in saving you time and stress.

Got any suggestions of your own on how you keep things organized and your code running smoothly? Write us a comment!