Tangent Snowball

Front–End Conventions

The following is a series of guidelines for writing front end code, based on our own knowledge and preferences as well as elements from other guideline documents that we found useful.

Things like only using tables for tabular data haven't been covered, as we'd consider these things obvious. Right?

This document does not address browser support directly as this is covered in other materials.

General

HTML

Quick rules that don't need explaining

  1. Where possible, use the same markup for similar elements, controlled by a parent class to control style differences. For example, product display in different situations - single product, product lists, etc.

Write valid markup and indent it properly

What?

There should be no validation errors in any markup produced, particularly in HTML flats given to backend to integrate into a system. Use a HTML validator such as Mgueury. The only exception to this is where markup is brought in by an external script, e.g. social media buttons.

Why?

Because writing invalid markup is lazy. Also, it shows that you don't really understand how it works. Also, if write it wrong and indent it badly, it makes it harder for the developers after you to figure out why it doesn't work.

Minimise markup and classes

What?

<div class="pageblock">
  <div class="page-header clearfix">
    <h1 class="pageheader-heading">Contact us</h1>
  </div>
  <ul class="pagelist">
    <li class="pagelist-li"><span class="bold">By phone</span> 012345678</li>
    <li class="pagelist-li"><span class="bold">By email</span> email@us.com</li>
    <li class="pagelist-li"><span class="bold">By post</span></li>
  </ul>
</div>

Believe it or not, the above happens. A cleaner version, where exactly the same effects could be achieved, would be:

<div class="pageblock">
  <h1>Contact us</h1>
  <ul>
    <li><span>By phone</span> 012345678</li>
    <li><span>By email</span> email@us.com</li>
    <li><span>By post</span></li>
  </ul>
</div>

Why?

Excesses like the above add to the page and CSS size and reduces the readability of your code.

CSS

Quick rules that don't need explaining

  1. No inline CSS. Ever.
  2. Comment your CSS.
  3. Classes should be lower case. If necessary, use hyphens.
  4. Indent where appropriate.
  5. Use your grid system to determine widths for elements (with the exception of non-grid dimension elements that need a width) and that only. The grid styles should not contain any visual elements e.g. colour.
  6. Text size declarations should only ever be as a percentage of the body text size (100%) and their use throughout the CSS should be minimal.
  7. Avoiding shorthand will increase flexibility e.g. margin-bottom:0 instead of completely redefining margin on an inherited margin.
  8. Keep selectors portable - don't define something useful like a pricetag class to only work within .productdetails.cameras .detailslist li .highlight .pricetag
  9. Don't over qualify selectors - .nav ul li a {} could probably be just written as .nav a {}
  10. Try not to be indiscriminate with your base classes - the site may expand beyond the current scope. For example - a {font-weight:bold;} - not all links may need to be bold.

No CSS hacks and minimise browser specific styles

What?

There are lots of these, mostly to help get around inconsistencies in the way earlier versions of Internet Explorer render pages. Common ones such as the star html hack have been around for ever...

* html #header {margin:0px 0px 10px 0px;}

These days there are more sophisticated ways of using Javascript to detect the browser and give the body a particular class to inherit from.

.ie6 .redbox {margin:0px;padding:1px;}

Why not?

We should be writing sites that use modern CSS techniques to deliver a quality visual experience, while letting our sites degrade gracefully in older browsers. True, the occasional browser specific rule is sometimes necessary but we shouldn't be maintaining any more than that.

If you need to write a browser specific rule, use the second technique above. It's much safer - how can you be sure another developer won't spot your hack, assume it's a typo and correct it without checking?

Organise and comment your stylesheet(s)

What?

One option for the structure of a stylesheet is:

  1. body and reset classes
  2. base typography and styles
  3. global layout - header, footer, etc.
  4. Modular/reusable styles
  5. Section/page specific styles
  6. Media queries/grid
  7. Browser specific classes

Differences may be appropriate depending on the type of site. For example, the grid might be more appropriate at the top if the site isn't following the mobile first principle, or it may be easier to include browser specific styles where they occur naturally in the layout.

Regardless, the most important point is that each section is clearly commented and you must include a guide at the top to explain the layout.

For larger projects, it's best to use multiple stylesheets, perhaps using a similar structure as above. If you do this, either you should be using something like LESS or the live system should be compressing all your stylesheets together.

Why?

It will prove useful later. Maybe not to you, but to someone trying to understand what you've done. Remember that not everyone thinks like you. Grouping styles together helps speed up maintenance and reduces the risk of version control conflicts.

Use meaningful class names

What?

An example of how not to do it...

<p class="style_16 word">content</p>

Why?

It's not always easy to come up with a class name that has some kind of meaning. But the example above, when combined with an disorganised, uncommented stylesheet, begs the immediate question - is this style used elsewhere? Can it be safely changed without breaking something else?

Classes should have names that reflect their function rather than their appearance, e.g. actionbutton and cancelbutton instead of greenbutton and redbutton.

Don't try to write classes that can be reused everywhere

What?

Ever seen anything like this?

<div class="floatleft centered bold italic bluebg roundedcorners tahomafont size14">

Why not?

Because to take the floating off this div you have to edit the markup, not the stylesheet - or risk defloating half the site. Class reuse is good, but this is taking it to an unnecessary extreme. Also, what advantage does this level of reuse give? The stylesheet is loaded and cached on the first page visit - after that all you're doing is adding to the size of the markup.

Don't use !important

What?

CSS uses a hierarchy. It's very carefully laid down. The !important rule lets you override that.

Why not?

CSS is hierarchical for a reason. Using !important breaks that structure and confuses the layout. Additionally, if you're finding that you need to use it, it's a good sign that you need to rethink the structure of your CSS.

Vendor prefixes

What?

For a lot of CSS3 attributes, there are browser specific prefixes to support the attribute in older versions of the browser. They were often introduced to allow support for that feature before it became part of a standard.

For example, box-shadow for older webkit browsers is written as -webkit-box-shadow.

It will be a project specific decision as to whether or not to use vendor prefixes to support these slightly older browsers. If the project requires it, consider using Prefixr to make things easier.

Why?

Including all the vendor prefixes can make a stylesheet bigger and more cumbersome to maintain. In theory we shouldn't use them simply for the same reason that we shouldn't make any effort to make CSS3 effects work in older browsers that don't support them at all.

Javascript

Quick rules that don't need explaining

Use a single top level object to namespace your code

What?

Bad:

    function geticons() { ... }
    geticons();

Good:

    var snowcone = {
        geticons: function() { ... }
    }
    snowcone.geticons();

Why?

Javascript has a global scope problem which is best worked around by using this approach. It also helps to enforce a much cleaner way of organising the code.

Validate your Javascript

What?

Run your code through something like jslint or jshint before you commit it - even if it is working fine for you. Jshint can be configured as part of a pre-commit script for git.

Why?

Some browsers (IE7) will not run code at all even though other browsers are quite happy to - just because a stray comma may be lying around somewhere.

Where possible*, avoid using Javascript to alter layout on page load

What?

Let's be clear - Javascript can and should be used for all sorts of things including altering the layout of a page. But where possible, this should only happen when the user interacts with it - Javascript shouldn't be used as a shortcut for fixing browser compatibility bugs on page load, e.g.

    $(document).ready(function(){
        $('.ie6 ul').css('margin', '5px 5px 5px 20px');
    });

Why not?

It's the wrong tool for the job. If the markup and CSS doesn't work in all the browsers required, then it needs rewriting. Styles should go in the stylesheet - developers shouldn't have to hunt through lines of Javascript to figure out why the page isn't rendering as they expect.

* Of course, in some cases Javascript may have to be used to set the height or width of something, but stuff like this should be employed in a pragmatic way.