Making Front-end Development a Team Sport

I totally dig the idea and understand where the sentiment stems from, especially after knowing some “horror stories” of code past. We’ve all been there: you inherit files to work on and you kinda get that feeling like you get after watching a Hoarders or Intervention marathon. “Why would anyone do that?” is a question that comes up a lot when trying to maneuver your way through these front-end template heirlooms. You may even find yourself asking, “Why did I do that?” when returning to old code.

There’s no shortage of reasons that code ends up messy. Sometimes, it happens when code switches hands a lot. Perhaps one developer on the job preferred tabs and hyphens, while another developer later swore by spaces and underscores. Sometimes, there are tight timelines. Late nights might mean that you skipped a few ARIA roles, added more divs than you probably needed and didn’t bother to go back and clean up some superfluous line breaks. Sometimes, it’s even your own files that are messy ones; You wrote CSS rules before you knew how much overhead would be added when you strung together five selectors in your CSS declarations, or before you understood the drawbacks of going a little nesting crazy in your LESS selectors.

Enter the Almighty Style Guide

With style guides’ recent rise in popularity, teams have found ways to make it easier for all those writing front-end code to follow the same set of guidelines, keeping conventions common and code clean. From GitHub to Bootstrap to CSS Wizardry to OOCSS Standards, there is no shortage of documents stating the preferred way to front-end. I really love these, so I found myself wondering: how would these style guides translate over to client services for different projects and team sizes?

As Yesenia poignantly discussed a couple of weeks ago, not every project is created equal. On top of that, not all developers work at their maximum efficiency level following the same set of rules. Perhaps the next client project you work on requires underscores in class names or jQuery UI modules. Or, maybe on your internal team, Jane works better using LESS, and John works better using Sass. While you can hope to convince client team members to change class name formats based on your semantic reasoning or ask them to utilize LESS instead of Sass, that might not be the most cost-effective change for their organization.

But What If I Don’t Have a Guide?

If you are without a style guide, either due to time restrictions or a preference against homogenization, how do you avoid the ever-plaguing dilemma of having too many cooks in the HTML kitchen? You don’t have to create a 300-page style guide or strict onboarding documentation to avoid the potentially harrowing results of multiple front-end developers working on the same project. We have other options, too!

Enter Organization and Sass

First, before getting into the code, we have a template kickoff meeting to assess the designs and split up tasks by groups of sections and modules. Doing so minimizes the chance of future interference. Second, I utilize starter files to create the beginning of each project. I like to use Sass and create separate .scss files for each major module we defined in the kickoff meeting. This leads to the CSS folder looking something similar to:

• _general.scss
• _global.scss
• print.css
• screen.css
• screen.scss
• pieces/_carousel.scss
• pieces/_footer.scss
• pieces/_header.scss
• pieces/_layouts.scss
• pieces/_nav.scss
• pieces/_search.scss

The general file holds all the basic styles for all HTML elements to make sure no element goes unstyled and takes browser defaults. All element selectors (no classes/IDs) go in this document to cover the base styling for everything from an H5 to a blockquote to a table. One resource can tackle the general styles, and after those are complete, the other devs will know if adding a class name on an element is necessary to override or tweak a base style.

The global file holds Sass Mixins. This file is shared amongst all projects utilizing Sass, and we update it periodically with new or more efficient mixins.

The screen.scss file imports all other files and holds smaller updates to styles, such as .left and .right classes, or read more links—styles that are beyond general but aren’t large enough to demand their own partial. The screen.scss file will be modified by all on the project, as needed. Later, that file is compiled into a single screen.css link.

Print.scss is, well, pretty self-explanatory and can be tasked to one resource.

The layouts file holds the different column and grid structures of the site. This is another task that works best handled by one person. Then, once the foundation is set (one-column, two-column, sub-column on left, sub-column on right, etc.), it can be tweaked for all possible layouts.

From there, the files within the pieces folder can be split up amongst the team. Since the files are divided as self-contained modules (think SMACSS) and all are based on the initial general styles and layouts cascades, working on one should not affect any other part of the site. Devs can work independently and smarter (and with less !importants). Splitting things up this way also makes it really easy to find and revisit a module for alterations. The carousel code later gets redesigned into a static hero image? The slider pagination needs to change from thumbnails to arrows? No sweat. You know exactly where to find the styles to remove and change.

What about Variables?

Variables are one of the most awesome parts of CSS preprocessors, and we utilize them, as well. It’s best to keep the variables in a place the team can find, such as the general file, but it also helps to keep fellow members in the loop of updates and changes to these variables. We know we always want to avoid duplicate code, and that applies to variables too. We don’t want to end up with a $olive and a $green that reference the same hex number. One technique we have tried in an effort to reign in variable declarations and keep everyone aware is to use an editable doc or a Basecamp writeboard to house a listing of the values. It helps to leave comments in the doc when new variables are added (with an explanation why), so everyone knows they are up for grabs to use in their own work. This communal doc is also great for getting the design team involved to help set initial variables like the base text size and line heights, as well as base font declarations. It also keeps communication open throughout the build and helps avoid mistakes. So, if I let the project team know I’ve set a gutter-width to 30px, a designer could let me know it should actually be 25px if a design was updated or if I copied a value incorrectly.

Communication is Your Friend

We can also never underestimate the power of a well-detailed commit message. We use Beanstalk and Git, and, recently, I began to use Tower. Whereas Git through Terminal doesn’t really prod you to be very eloquent with your commit messages, the Tower interface lends itself to writing thorough exchanges using their subject and message fields—a good habit to have when trying to track a change or understand the newest additions to the shared project.

On a similar note, comments have always been super helpful and embraced by developers. With Sass, I like to use the // syntax to denote internal comments that can be deleted at project end—things like “//Do we still need this variable?” or “//JL: I’m still trying to make this work. Blargh.”

So Many Options!

Style guides are great tools and might be a great fit for your team. If they sound like your cup of tea, be sure to check out Chris and Anna’s round-ups. If Partials are more your speed, see how it worked for Beanstalk. Or maybe you’d prefer a combination, so Jeremy’s Pattern primer might be more up your alley. Whichever route you choose, remember that you can combine any or all of these solutions to be the answer for you and your team, and that answer is sure to be a better approach than this: How To Write Unmaintainable Code.

Back to Top