Improving Your Process: Establishing Style Guides

I’ve been huge on process for a long time now. In fact, I’d say that I consistently spend a significant amount of my workweek analyzing how our process is working for us. Things change in an instant, especially in our industry. Things that worked for our process last year have become hardly applicable, and new ways of thinking are constantly required.

I like the business end of Web design. I’ve come to the conclusion that one of the reasons I like it so much is due to my enjoyment of problem solving. Web design as a business is a problem, plain and simple. Everyone has their own way of doing things, we’re working in a medium that many of our clients don’t fully understand, and it’s sometimes very difficult to completely resolve the final terms of an agreement and be fully confident you’ve covered all your bases. This is something I like thinking about, something I like dealing with. If you’re not in the same boat, I hope you don’t plan on freelancing being a walk in the park. The business end is just as big of a deal as the design/development end. You want to get paid.

Style guides? For code?

A style guide is a straight and to the point document that outlines how you should be formatting your code. It covers indentation, alignment, spacing, tabs, naming, and just about every other aspect of writing code apart from the logic itself.

Whether you’re writing a script, some markup, or programming, you have a way of doing it. You put your brackets in a certain place because either it looks better to you, or your teacher told you to write it that way. The same goes for the spaces you include in your arguments list, your array declarations, and so on. These are important details to consider, especially when you’re looking at someone else’s code.

Even if you didn’t realize you did it yourself, looking at someone else’s code can just come off as… unorganized. At first you can’t quite put your finger on it but you’ll find yourself asking “how the heck does this even work?” If you’ve ever had one of those moments, you’ll appreciate a good style guide in your workflow.

Structuring your style guide

There isn’t a real set of rules to writing your style guide(s); they will probably undergo a long series of revision as you realize the little details you’ve forgotten over time. I think coming up with a style guide is really good team based exercise, something I plan to finalize with my team over the coming weeks.

At my company, we’ll need four style guides to cover our workflow:

• HTML
• CSS
• JavaScript
• PHP

Currently these style guides are a work in progress, but as small snippets look something like this:

HTML

Our HTML style guide will cover things you’d expect to find in other code style guides, but certain aspects of formatting will be included in nearly every example. Things like the ‘closing’ comment for block level elements based on their class or id.

Block element with class

<div class="group">

</div>
<!-- /group -->

Block element with ID

<div id="address">

</div>
<!-- /address -->

Block element with class and ID

<div class="group" id="services">

</div>
<!-- /services -->

CSS

Probably the biggest rule to cover in a CSS style guide would be whether you’re going for single line or multi line, a debate that will carry us through the end of time. Front enders seem to be very passionate about their decision to go with one or the other, so we’re lucky to have a number of tools that will convert from one format to the other on the fly.

Comment Basics

/* ================ */
/* = MAIN SECTION = */
/* ================ */

.main { width:100%; }

	/* Child section */
	.child { border:1px solid #f00; }

Selector property value formatting

.section { width:200px; height:200px; }
.section #child { border:2px solid #f00; }
.section p { margin-bottom:1.2em; }
.section ul { list-style:disc; }
.section ul li { margin-bottom:0.6em; font-size:1.1em; }

JavaScript

We’re a jQuery house, so a significant portion of our JavaScript style guide will include jQuery-specific notes. Along those lines, more generic JavaScript instructions will be needed as well.

Conditionals

if( $('#address').height() < 100 ) {
	do_this();
} else {
	do_that();
}

Chaining

$('.group')
	.find('> p')
	.removeClass('someclass')
	.addClass('newclass')
	.find('ul')
		.addClass('targetclass')
	.end()
.end()
.slideDown();

PHP

I’ve always liked the way CodeIgniter writes PHP. Their guide is extremely in depth and I’d simply like to use that as our style guide as well. One of the best things about CodeIgniter’s style guide is that both correct and incorrect usage is outlined.

Bracket and Parenthetic Spacing

// INCORRECT:
$arr[ $foo ] = 'foo';

// CORRECT:
$arr[$foo] = 'foo'; // no spaces around array keys

Do you use style guides?

I’m becoming increasingly comfortable with the idea that at least some form of style guide, whether on a team or individually, is an extremely important part of the process. It helps with everything from readability to quality control and especially helps a team become that much more cohesive. Are you/is your team using style guides? Have you found them to be helpful, hurtful, or ineffective?