We’ve all been there. Time is short, so just bash out a bit of code, and as long as it works we can move on. Code is for computers anyway, right? Who cares what it looks like? Actually, how our code is formatted can totally save our bacon later, and save us time in the long run. Today we’ll be looking at how HTML should be written, and briefly touch upon CSS and PHP too.

Why does accuracy matter?

This might sound like it should be obvious, but it’s best to start here. Take a look at a little bit of code.

Show this in a browser, and you’ll see that it has the desired effect – it shows a single item in a bullet list. Look closely, though, and you’ll see that the closing </li> is missing. It’s not a problem though, because the browser still knows what to do with it. So it doesn’t matter if it’s technically wrong, right?

Wrong is still wrong, even if it looks right.

There are specifications telling browser manufacturers how code should be rendered, but it’s less clear on how it should look if the code is wrong. This can lead to inconsistencies between browsers, each interpreting your dodgy code in different ways. That unreliability can come back to bite you later on, and you could end up spending more time fixing it than if you had done it properly in the first place.

Now for our second piece of offensive code.

If you were to run this through the W3C HTML Validator, it would complain at you. It’s not valid. It’s not correct. It’s incomplete. But if you open it in a browser it will display exactly the same as if it were perfect. But while in this minimal example you could argue that it doesn’t matter, it would at scale. Once you’ve got a whole site of hideous invalid code, you’re sailing in dangerous waters.

So know your stuff. If you’re not sure how code should be used, look it up. Don’t guess, don’t settle for anything less than perfect. You’ll thank me later.

Valid HTML

I feel it’s about time for a beautiful piece of perfect code.

That, as far as I can work out, is the smallest valid HTML5 document possible. It breaks no rules. Run it through a validator and it will be all smiles and thumbs up. Not particularly useful, admittedly, but at least it’s valid. Turns out the <html>, <head> and <body> elements aren’t necessarily essential. It really is worth checking the specs every now and then, just to make sure you understand what’s valid and what isn’t.

Why does formatting matter?

This is another contentious issue, especially for beginners. Formatting makes absolutely no difference to computers. A badly formatted piece of code will likely produce exactly the same result as a perfectly formatted piece of code, as long as it’s technically accurate. Case in point, here is a valid but pretty incomprehensible piece of HTML:

It’s perfectly valid, but it’s been compressed, taking all the formatting out of it. And a browser doesn’t care in the slightest.

But – and here’s the crunch point – computers aren’t the ones writing the code, we are! We have to understand it too. Clear code is far easier to work with, especially if you’re picking up someone else’s code. Clear code also makes bugs easier to find and avoid. For comparison, look at the exact same code when it’s formatted properly:

Indentation makes the code sooooo much easier on the eye. You can visually see the hierarchy. You can see where an element ends without having to find the closing tag. And if your code editor happens to support syntax highlighting (it does, doesn’t it?) then you’ll also be able to see which are tags, which are parameters and which are values.

So what should it look like?

Thankfully, we’re not exactly fumbling in the dark when it comes to how best to format our code. People have talked about this for years, and there are established recommendations on how we should do it. Here is a brief summary to get you started:

  • Use lowercase in tags.
    • <a href="somewhere.html">Link</a>  YES!
    • <A HREF="somewhere.html">Link</A>  NO
    • <A Href="somewhere.html">Link</a>  NO
  • Use 4 spaces for indentation. Code editors can usually be told to automatically maintain your current indentation level, and you can often specify whether you want to indent with tabs or spaces. 4 spaces is the recommendation.
  • Know which elements are self-closing. Here are a few examples:
    • <meta name="description" content="Hello world.">  Self-closing
    • <img src="bunny.jpg" alt="Here's a bunny">  Self-closing
    • <p>Here is a paragraph.</p>  Needs closing tag
    • <script>console.log('Hello world');</script>  Needs closing tag
  • Use inline and block elements correctly. Inline elements can be nested inside block elements. Block elements shouldn’t be nested inside inline elements. And some elements automatically close others if used incorrectly.
    • <p><span>Hello world</span></p>  Inline inside block = YES
    • <span><p>Hello world</p></span>  Block inside inline = NO
    • <div><p>Hello world</p></div>  YES
    • <p><div>Hello world</div></p>  NO (child <div> will automatically close the opening <p> tag, making the closing </p> tag invalid)
  • Stop using old elements
    • Use <strong> instead of <b>
    • Use <em> instead of <i>
    • Never use <blink>
  • Use double quotes for HTML parameters. This is for consistency, and especially comes into play when using inline Javascript.
    • <a href="something.html">Link</a>  YES
    • <a href='something.html'>Link</a>  NO (technically valid, but not recommended)

Don’t forget the styles

The same principles apply to your CSS: the computer won’t care if it’s ugly, but you should. Again, here are some quick pointers:

  • Indent with 4 spaces
  • Use spaces correctly
    • font-weight: bold;  YES
    • font-weight:bold;  NO
  • Don’t over-specify elements
    • #emphasis {}  YES
    • .something #emphasis {}  NO
  • Use comments to add clarity
  • Separate files for context
    • For example: layout.css, type.css, header.css, blockquotes.css, product.css
  • Don’t combine styles onto one line

Depending on who you talk to, there are some other conventions you could adhere to, like ordering your CSS attributes alphabetically, or by function. There’s also a case to be made for always using classes over IDs, but that’s up to you.

And finally, the PHP

Rather than trying to summarise this and get it wrong, I would instead direct you to the excellent PSR-1 and PSR-2 documents, which outline exactly what PHP should look like. But, to whet your appetite, here is a bit of PHP code (taken from the PSR-2 documentation) that keeps the pedants happy:

Note the use of line breaks, spaces, blank lines, brace positions, capitalisation, indentation, and function visibility. If this were a real-world bit of code I would want more comments in there, but it’s a good start!


To get you going in the right direction from the outset, I’d highly recommend you take a look at html5boilerplate.com. It’s available as a Git repository, if you’re into that kind of thing (and if you’re not, you should be), or you can just download it as a zip and get coding. Think of it as a foundation of good quality code on which you can build your actual web page.  Here are some other HTML related resources you might appreciate:

And some similar resources for CSS:

And finally, some for PHP:

Also, make sure you’re using a code editor that is fit for purpose. Don’t use Notepad.exe. Use something like Atom, Brackets, Sublime Text, or even PHPStorm if you’re properly serious.

Leave a Reply

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