Laying out your HTML markup

Posted 3 December 2010
21 comments so far.
Tweet

I had a comment about my HTML the other day, it was a fairly valid one about how to make the source code a little more legible, and that I should indent it.

Maybe I should, but this got me thinking I should buckle down and make it more legible and neater, heck I am a designer after all.

Actually its pretty good.

I opened Coda to take a look and see how I can improve my code and realised I do try and make it as legible as I can, BUT in the CMS format.

The majority of sites I create are in CMS called Textpattern and therefore contains alot of txp tags to generate links and dynamic content.

A normal list of links might look like this

<ol>
<li><a class="active" href="#">An ordered</a></li>
<li><a href="#">list of</a></li>
<li><a href="#">Links</a></li>
</ol>

Great, Job Done!

What about in a CMS?

<ol>
<li <txp:if_section name="ordered">class="active"</txp:if_section>>
<a href="<txp:section />/An ordered/">An ordered</a>
</li>
<li <txp:if_section name="list">class="active"</txp:if_section>>
<a href="<txp:section />/An ordered/">list of</a>
</li>
<li <txp:if_section name="links">class="active"</txp:if_section>>
<a href="<txp:section />/An ordered/">Links</a>
</li>
</ol>

So you can see I’m breaking down each ‘function’ to a line on its own so that when I come back to it later I can make better sense of what I’ve done.

Below is what the outputted code will look like, still acceptable but not as easy to read as the first example.

<ol>
<li>
<a class="active" href="#">An ordered</a>
</li>
<li>
<a href="#">list of</a>
</li>
<li>
<a href="#">Links</a>
</li>
</ol>

Stop messing about and use one line?

The example above is very simple and I have some quite complex statements on some sites that will cause the HTML to look awful, but it works and google can read it. I can still indent my code but I don’t think I’ll change my CMS coding habits a great deal.

What do you do?

This is not gospel and I’m by no means preaching as everyone has their way of coding, how do you do yours?

cms, code, layout, textpattern

Comments

# Alex Older 532 days ago

I indent all the code I produce up to a point. I don’t indent every nested tag there in little point in doing so.

Being mainly a WordPress dev I use inbuilt functionality to build my nav, meta information and more so the code it spits out I have no control over how it looks, but if I was to pass my WordPress theme to someone else for example they would just see the function calls so I sleep well at night.
# Paul Annett 532 days ago

If you want to continue separating each tag onto it’s own line, then it would indent like this:
http://twitpic.com/3cfpyz/full

I personally wouldn’t go to that extent. I’d do something more like this:
http://twitpic.com/3cfqyn/full

Indenting code is not about designers wanting neatness, it’s about making the site easier to maintain and debug, should anything go awry.

The small example above doesn’t really show that, but put that in the context of a page of code and the hierarchy of the markup becomes visible. It’s then easier to spot if a tag has been missed out in error.
# Cole Henley 532 days ago

I tend to indent with a new line for each block level element, see example at pastebin
# Dan 532 days ago

I’m with Cole, I indent every block-level element, maybe that’s from using PHP? I’ve always used a single tab per indentation level – I know in some languages they get arsey and insist on a single space, double-space or 4 spaces.

So long as it’s legible and clear to a developer other than yourself, that’s the main thing isn’t it?

If we’re talking about layout… when it comes to CSS I indent element properties but also alphabetise. A colleague did that and when you do it, it makes so much sense. Makes is faster to find what you need ;)
# Paul Annett 532 days ago

If you look at the second example I posted in my comment, you’ll notice that I’m with Cole too. I just didn’t phrase it as nicely ;-)
# Oliver Ker 532 days ago

I think coding and indenting client side and server side can be slightly different?

I’ll be striving for indentation more at block level, but wait and see how that effects the client side code on the more server side stuff I do.

Nice to read the comments, thanks all
# Ryan Downie 532 days ago

This is how I roll, on the lines with with Cole and Dan.
http://cl.ly/342U2F0y0z0K0C3v0V2u the reason is the ease of use to quickly scan the document when reading.

It is also the same with CSS, I am a bit of a organization freak when it comes to writing code. I do that also in sections but on one line.
http://cl.ly/0W361O2s1T351g0E2e16
# Chris Garrett 532 days ago

Indenting code is entirely about maintainability, especially in a team environment, so it’s futile to try and indent for the client side, stick to writing legible code on the server side.

I doubt our code looks at all legible in the browser, we use HAML so have no control over the final output. If you’re a serious developer though, you’ll use some form of inspector rather than source view, and they interpret and render on a nodal basis anyway.
# Pete 532 days ago

I’m with Cole and Paul as well. Often though it’s out of our hands to a certain extent when 3rd party software gets involved.

Wordpress has a nasty way of indenting sometimes, and if you’re using HAML, or .less (if we’re talking css neatness too) and you’re compiling and/or compressing code, then all your neat code soon doesn’t look so neat all of a sudden.

These days I’m happy if the source files (the .less files, .php files etc..) are neat to edit my end (or when passed over to the client) then I think that’s fine. How they get indented in the source code bothers me less.
# Sam Hardacre 532 days ago

Personally, I find indented code harder to work with. It’s easier to read but not as easy to digest, at least in my own muddled up head :)
# Chris Garrett 532 days ago

@Sam that’s interesting. With XML’s nodal nature, indentation seems like the logical way of visualising a document’s structure, but I guess we all think differently.
# Gavin Elliott 532 days ago

+1 with Paul and Cole. I’ve always done it this way. I think it’s the way we’ve been ‘brought up’ into coding. Depending on if you’ve worked within a team or as a freelancer would also maybe change your perception on what the better way to do it is.
# Dan 532 days ago

@Sam Horses for courses, eh? I just find if you have any number of declarations on one line it just looks like a mess. By seeing every property on a new line, the line length is short so I (personally) find it easier to scan ;)
# Sam Hardacre 532 days ago

@Chris – Yeah, I think my view is, in part, shaped by conditioning. I learned from people who wrote without indentation and after 7 years, it’s a hard habit to break :)
# MrQwest 532 days ago

I’m with Cole (Dan & Paul), indenting the block level elements. I find it easier for me that way.

I too use Textpattern, and have also broken that down like your first example Oliver – it’s generally easier to read for me when it’s broken down like that but I do realise that that can often make code harder to read on the output.
# Chris Garrett 532 days ago

Start using Python or HAML and you soon will ;)
# Chris Garrett 532 days ago

@Sam Start using Python or HAML and you soon will ;)
# Sam Hardacre 532 days ago

@Dan – I do use line separation etc to organise my HTML. I tend to only group things on one line when there’s a relationship between the elements used:

<label>Name <input type=“text” /></label>

Just seems to make more sense to me
# Dan 532 days ago

@sam I just realised I got off topic and was talking about CSS from my last comment ;) I’d not normally wrap an input with a label though, just use ‘for=”“’ to associate…(maybe being far too picky over a quick example here!)

[Oli – your comment form strips \n from it so the code I dropped in before posting this got new lines stripped and kind of defeated the point…just so you know!]
# Mike Robinson 532 days ago

One line might work if you are just doing HTML with no dynamic layer but I find that the added complexity of template code, where loops or logic are involved, can make this difficult to read.

Personally I indent per block level, which includes my CMS/template tags, and don’t worry about how it is formatted on the final output. The code should be most readable in the development environment to aid maintenance, the output can always be formatted by tools like Web Inspector/Firebug for those inspecting the source.

What about spacing between grouped blocks at the “same level” (e.g. two divs directly within the body)? Do you separate these with blank lines, comments, or have them separated by a single line break?
# Jim 532 days ago

I always indent in my editor. However I use Rails which outputs the most appalling HTML when using ERB templates (i know, i know, i should be using HAML!) so my output is generally a little “messy” in places.

I indent for block level and if generally keep related elements on one line. I find it much easier to spot those dreaded missing closing tags if everything is nicely indented.

Oliver Ker Design