Improving Your Process: Establishing Style Guides

Posted: March 29, 2010 Comments(7)

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?

Get my newsletter

Receive periodic updates right in the mail!
  • This field is for validation purposes and should be left unchanged.

Comments

  1. While I stick to my own conventions when I code I have never thought of taking it to the point of actually developing a style guide. However I can see how useful it can be when you have more than one person working on a given project (typically we have at least two if not three).

    When you have to start looking through to see what other people did legibility and consistency is really important. This will have to be something I work on in the near future.

  2. Hey Jonathan,

    In this case I’d prefer to use the term ‘Coding Standards’ (though I’ve seen people use it and ‘Style Guide’ interchangeably). I think of a Style Guide more along the lines of including what colours, fonts, image sizes for various sections etc. a particular website design. An example of what I mean is the Drupal.org Redesign Style Guide (https://infrastructure.drupal.org/drupal.org-style-guide/index.html) done by Mark Boulton.

    I usually try to follow the Coding Standards (if there is one present) for whatever framework, CMS, programming language etc. I use. For example, since we do a lot of work with Drupal where I work, we adopted much of the Drupal Coding Standards (http://drupal.org/coding-standards) where it concerns PHP and a little CSS. For HTML, CSS, JavaScript we went with the Fellowship One Coding Standards (http://developer.fellowshipone.com/patterns/code.php).

    Good write up though Jonathan.

  3. For us, the “why” of a styleguide is simple – Teamwork. When we’re all following the same conventions – even to file naming, there’s a lot less guesswork as to what someone else might have named something, etc. Spaces, UC/lc, hyphens – all equally as important as commenting divs and css 🙂

    I guess after 15 years or so of creating for the web, some things evolve – experience sets the tone.

  4. At work we follow a style guide / coding standard, but not in the conventional sense. Our general mantra is that any code you write should look similar to that of the code surrounding it. While each developer on the team have their own personal preferences, we have started to gravitate towards a singular style based on working together over several months.

    It saves the overhead of having to sit down and agree upon the ‘right way’ but at the same time if I have to go fix a feature, at least all of the code I need will look relatively the same and easy to follow.

Leave a Reply

Your email address will not be published. Required fields are marked *