HTML Formatting

April 29, 2004 | View Comments (48) | Category: Web Mastering

Summary: Why I think quality code formatting is important.

A reader asked me not too long ago if HTML code formatting was important to me. To me any code formatting is important I thought as I responded to him. Recently however, I have been looking at the code of different sites (CSS & HTML) and find it difficult to figure out how certain effects are achieved due to the sloppy code.

Ever since I was a full-time programmer I have been obsessed with clean code. I wouldn't be suprised if this was one of the reasons why Zeldman likes to handcode his site. Having control over the code and how it looks is a luxury nowadays it seems with the way CMS's butcher code.

Looking Back

The reason that clean code becomes so important to me is because when I look back at the code I like to be able to figure things out quickly. The cleaner the code, the easier it is to wrap my head around everything.

I notice a lot of people do not indent their code at all and was wondering what benefits they found in this besides shaving a couple of bytes off in file size?

Getting Worse

CSS files are growing larger (this is becoming a serious problem) everyday and because of this I find many designers cramming their code together. That in itself makes it hard for me to study, but I wonder if it has any effect on them? XHTML files on the other hand are getting leaner so how the code is formatted may not matter that much.

I admit to the occassional laziness of not properly commenting my CSS file, but usually I am pretty good at that kind of stuff. Quality looking code to me entails whitespace and comments and offers greater long term benefits that some people tend to overlook. Do you have any coding standards?

Trackback URL: http://9rules.com/cgi-bin/mt/mt-tb.cgi/222

Comments

I agree generally that commenting is useful, but it's a personal preference really. I mean, the only "hard" reason to comment code is in terms of professional courtesy in case the project gets handed off to someone else.

Otherwise, it's like the unorganized debate between my wife and I. Sometimes, I have a tendency to drop stuff where I'm standing. It's unorganized, but I know where it is. My wife likes to come in behind me and place all my stuff where it "should" be in a logical sense. Next thing you know, when I'm needing that particular item again, I'm totally lost as to where it is.

To bring that example back to the topic, just because it's unorganized and sloppy to you doesn't necessarily mean it is to the designer, and if the possibility of it being handed off to someone else is nill, then it shouldn't really be that big a deal - right?

I think some designers do that on purpose so you won't have the luxury of learning from their efforts. As you've noted several times before, some designers are quirky like that.

Mark (http://www.lightpierce.com/ltshdw)

I just had a conversation about this a few days ago. We were talking specifically about CSS and how I prefer a long, verbose file simply because it's easier for me to find my way around after months of not touching it.

I don't have any strong standards as far as format goes. I think my own preferences are differernt than most. For example, I don't like my code indented to much as I find that hard to work through at times.

I don't comment much as I find too much commenting to be a bit distracting, but I will do it where I feel it's needed.

Seems like as a site grows and is adaped the code begins to develop some bloat. I notice this on Asterisk* -- although I've got no problems getting around it. It's a bit more of a concern when working on something that will either be handed off or inherited down the road.

As someone who has inherited reams and reams (and REAMS) of code, I do try my best to clean it up for those that come after me. I'm not the best at it, but I think I can say I'm better than anyone who came before me. ;)

Keith (http://www.7nights.com/asterisk/)

[off topic]The plural of CMS is CMSs (or possibly even CMSes), not CMS's.[/off topic]

I totally agree. I always indent my markup with tabs. Interestingly, I use a fairly uncommon tab setting of 2 spaces (I believe most people use 4).

However, when coding CSS I myself find it easier to navigate they stylesheet when I have the selector and rules on the same line. Something like this:

div#content { width: 100px; background-color: #eee }

So basically, selector, space, opening brace, space, rules (space seperated), space, closing brace.

David House

I usually do not indent my code. I do it more as a personal preference because I hate having to scroll horizontally to see stuff, and I am not a fan of having wordwrap turned on in Homesite. So having everything aligned to the left makes it easier for me to read through my code.

But in all honestly, it really is a personal preference. I have noticed that most programmers prefer to indent their code, but their code is more complicated and they benefit more from that formatting.

Jeremy Flint (http://www.jeremyflint.com)

Many authors that develop for traffic-intense websites go even further and obfuscate the code that is delivered to the browser. The thinking is that it will help in overall optimization. You would have 2 versions of the document, one on the local development platform with juidicious whitespace and well-commented code. When it is time to publish to the web the code is obfuscated so that all comments and whitespace is taken out. Tools like this do the job nicely.

Those who do it this way say that the view-source option is a hold-over from the old days of the web . They would argue that catering to other developers who happen to view the source on your website isn't a valid reason for not obfuscating the code that is delivered in a production environment.

I certainly understand the point. By delivering well-commented and well-formatted code to end-users it only benefits hackers, competitors and developers trying to learn. The end-user, it is argued, doesn't benefit at all from unnecessarily large source files.

Terry (http://www.xdevdesign.com/)

That is, of course, the innocent end user who's just looking through your site as an example of a well written website. With semantics still needing to be promoted, I think this is a valid scenario.

David House

Whoops, forgot the word 'except' in the above comment :)

"That is, of course, except..."

David House

RE: #1 Mark

"Professional Courtesy" as you put it, is hard enough of a reason for me to comment anything that anyone else may ever look at. Since this is a question of HTML Code Formatting I'll assume that you mean you do not comment your HTML code. And generally that is ok (unless you are doing something particularly odd). I generally don't comment my static html (I used to comment sections of code but since switching to CSS: <div id="header"> is usually enough to get the job done. I also don't comment my CSS unless tricky stuff is going on, or I might forget the reason I put a particular rule that looks out of place.

But as far as programming goes, I generally try to comment even the most mundane bits of code as

I deal with many different web apps, many of which I didn't write. So mainting them is a chore. Every little comment helps.

The problem I sometimes with commenting code, is that some simple bits of code make perfect sense to me while I am writing them, so I find it hard to write a comment about it, but that simple bit of code 6 months later might not make the same sense at first. So my tip here is even if your comment sounds inane and obvious, write it, you never know who it might help.

Back on topic: I do indent my HTML almost religously because most of the time it is littered with CFML and with all those tags it can get quite hard to read sections of code (thank God for code collapsing in Homesite/CFSudio)

I hand code all of my pages because I can't bear to let some WYSIWYG app sully my good name!

Jason

But David, as harsh as this might seem, it's not really the responsibility of the designer to provide you (or anyone) with an environment to learn or benefit or even to promote semantic markup - that's what books and school is for.

Furthermore, how to seperate the "innocent end user" form the piggy backer looking to get some free knowledge off your hard work?

Mark (http://www.lightpierce.com/ltshdw)

#10

[offtopic response]I too use a 2 space indent, less than that and you lose the benefit of indenting, more than that and anything more than 2 levels of indentation gets hard to read. Most editors I've worked with default to 4 or 5 spaces, and it seems that a lot of folks just leave it at that.[/offtopic response]

On the other hand, I find keeping the css selectors and rules on the same line to be more confusing.

Commenting can be critical even if you're the sole developer, especially if you spend a lot of time jumping between projects, especially if your short-term memory is as bad as mine can be.

Ultimately, though, no volume of whitespace or commenting can save my code from being utter crap :)

igner

#11

#9 Mark:

Dave has discussed this many times in the past with regard to CSS Zen Garden rip-offs. However I myself am using no groundbreaking new techniques I need to hide from the world, I don't really mind if my CSS is stolen as it's not the greatest design in the world and I came up with it in a matter of hours, my XHTML is up for grabs for anyone that wants it. I realise this scenario is not the same for everyone, especially the second one.

But the line stands: books are nothing in speed compared to online articles (when was the last time you saw an up-to-date book on programming? When was the last time you saw one in a public library? They often take years to get written and published) and by the very definition of HTTP your code is out there and there's nothing you can do to protect it from Joe Codestealer and Jane Lazywebdeveloper.

David House

#12

Jason -

Here's how I would approach this.

If I were doing something that I knew was groundbreaking and might be useful to the web design community at large, then I would comment either the HTML or the CSS or both.

If I were working as an employee, I would comment everything for the benefit of whomever might take my job in the future - because everything I do as an employee belongs to the company anyway. It's a professional courtesy to my employer and future replacement.

In terms of a job that's not ground breaking in any way and not at risk for being turned over to anyone, or something I hold complete creative control over, I will comment when I feel that it will explain something to my client contact or help me to remember something in the future.

If someone wants to look at the code, feel free - but time is money, so my focus is on finishing the job for the client, not putting together nicely formatted code for someone else's learning benefit.

Mark (http://www.lightpierce.com/ltshdw)

#13

I can't stand code that isn't indented, whether it's HTML or Java or whatever. I get so attuned to a particular formatting style that it gets really jarring to see it any other way.

Though I don't actually indent HTML quite correctly, strictly speaking, because I would end up with too much pushed off to the right off my screen. I tend to keep html, head, body, and big divs or tables all at the beginning of the line, and only indent their contents (this is especially true in my JSPs, where I often have c:choose/c:when/c:otherwise tags and c:forEach tags that end up making the code more indented).

I'll also feel free to break attributes up onto different lines in order to keep the lines from getting too long, but of course then the attributes have to neatly line up with each other. :)

It's hard not to be really picky and anal about formatting. Personally, I really like to use tabs that are 3 spaces wide (but that are real tabs, not spaces), but at work everyone uses 4 spaces, and the line length is restricted to 80 columns. Yuck.

I don't care too much if the indenting and formatting are garbled when you view source - it's the source code on the server - what you're editing - that really matters.

Jennifer Grucza (http://jennifergrucza.com)

#14

#11 David (OK, I can start doing this ;))

Just as I'm not likely to go out of my way to comment something for someone (in terms of how I outlined it in #12), I'm also not going to go out of my way to bury my CSS through multiple file call outs or hide the HTML w/some javascript.

My point is that the burden of learning is placed on the initiative of the student.

If someone wants to figure out what I did, then do the view source thing and figure it out. If one still can't figure it out and really want to know in an "innocent" kind of way, then send me an email.

If one is honestly trying to learn, I'm all about helping - but if I discover someone has ripped me (as has happened to Andy Budd and countless others), then I'll rip that someone a new one.

Mark (http://www.lightpierce.com/ltshdw)

#15

I indent sometimes, but not usually much with straight HTML, unless there's something I specifically need to work with that's confusing (eg, anything nested... tables, lists, divs)
I'm much more likely to pay attention to formatting details if I'm doing anything dynamic... indenting becomes far more important when you start working with nested if statements, loops, and the like.

But I don't give a rat's $randomAnatomy about someone looking at view source on the output file. I'm all for stripping out everything except the whitespace in CSS and JavaScript (and even that if they ever come up with a really reliable space to do it without causing errors), and saving that extra 1k of bandwidth for myself and the end user. If someone wants to see how I did something, they can grab the output HTML and run it through a source formatter easily enough. Actually, I often do that with code I've written just so it DOES look pretty in case one of my coworkers needs to go in later and edit it.

JC (http://thelionsweb.com/weblog)

#16

Oh, and FWIW I use tabs to indent, with my editors set to default tabs to 3 spaces except for .txt and .tsv files, where it's 5 or 7, depending on what I last left it on... those are easier to work with when there's extra separation

JC (http://thelionsweb.com/weblog)

#17

I hear ya with respect to big CSS files, Scrivs. Our latest site is sitting at around 26k all told, fully commented.

I have hesitated to break up the CSS into parts for the site, mainly because managing the site can get difficult once the file is broken up.

Anyway, more on topic, the main reason for not parsing it up is that I do create a 'compressed' version of my CSS for production sites, but lately have been keeping a 'non-compressed' version, fully commented' on the server along with the compressed one.

I link to the clean commented file from the 'compressed' file. If people want to see it clean, they can.

I'm also starting to notice that de-spacing and un-commenting my css may be relatively useless, as I am having pretty good success delivering my css compressed with PHP. Last I checked 75% of users (over 15 sites - average 2000 sessions a day) took down the gzipped version.

For the site mentioned above, 26k becomes 5.5k after gzipping.

Mike P. (http://www.fiftyfoureleven.com.com/sandbox/weblog/)

#18

Mike -- By "link to the clean commented file from the 'compressed' file" do you mean you just have the URL in a comment in the compressed file, or that you're actually still including the uncompressed file, through the compressed file, thereby not only killing the benefits of compression, but adding an extra 5.5k of your code?

re: despacing and so on in CSS and Javascript, I've noticed occasional odd things when that's done.. stuff gets centered that otherwise wouldn't be... weird. I tell our filter to leave that stuff alone and just work on the HTML part... still gzips all of it though.

JC (http://thelionsweb.com/weblog)

#19

Hey JC,

Just a comment, like 'hey theres better reading over here' etc.

I've noticed weird stuff with spacing too, most noticably a first-pseudo element problem that lost me an hour or so last summer.. Ugh! IE.

I'm more for zipping up the css now. Way more benefit, way less hassel.

Though I will say that as Scrivs mentioned above, by handcoding you get to know what does or doesn't clean well in your code. As a result, when 'cleaning' html or css, you can get a good handle on problem spots.

Mike P. (http://www.fiftyfoureleven.com.com/sandbox/weblog/)

#20

Oh, good. I've seen people do stuff like that in the past and then smack themselves across the head when they realized what was happening. :-)

IIRC, the main browser I had issues with when doing that was Moz, though IE did run into some centering issues on one web based loan application we have.

JC (http://thelionsweb.com/weblog)

#21

We have policy at work to always comment sections of code (this section is for this), and always indent the code for every page.

But, a client page usually consists of more than one page - most include 5-8 pages to make on client page. This causes the resulting file to have somewhat strange indents, as ach of the 5-8 files is indented as a separate file. We also use server-side functions for as much as we can.

At the same time we use code compression. An automatic filter removes any lines, comments or other spacing in general. This turns the client code into one huge, single line, chunk of code (completely impossible to read). But, it speeds up the page by almost 30%.

Something to notice is that the server only has one fully commented/indented file. The compression happens real-time on the server when a user requests a page.

For CSS files, we are just beginning to adjust these to make them smaller. Instead of margin-left: xxpx; margin-right xxpx; we are starting to use: margin: 0px xxpx 0px xxpx;. As well as not repeating styles. That really makes a huge difference - but again is harder to read on the client.

For me it could not care less about how the code looks in view source on the client side. I care about how fast my sites are - and compressing code makes it faster. On the server-side, it does matter a great deal - if you find a bug, or need to implement a new feature, you want to be able find your way around quickly.

BTW: For my personal site, I am a bit more relaxed about these things :)

Thomas Baekdal (http://www.baekdal.com)

#22

Lately I’ve taken to indenting religiously with my HTML. Tabs and newlines everywhere (except when they introduce whitespace bugs in certain browsers). I rarely comment, mostly because my code is pretty lean and self-describing.

As for CSS, I have yet to come up with a method of organization that I like enough to use more than once. I’ve done the “elements, then classes, then IDs, then contextual selectors” thing, and a few other methods. Usually I end up writing the code in nearly the same order as the elements appear in source code, since that’s usually how I write it the first time. There’s no real rhyme or reason to how I set up a CSS file, but I do indent and tab everything I can.

I comment the hell out of my server-side code though, and usually for Javascript code as well. Otherwise, I really tend to forget what I did or why something works the way it does.

Vinnie Garcia (http://blog.vinniegarcia.com)

#23

I have a few simple guide I use when dealing with markup. If I use alot of nested divs then I comment the closing div so I know what goes where. I usually align the div tags to the left and add one indentation and a carriage return between the start and finish of paragraphs, lists and such. As for the CSS I usually comment on hacks and things such as where the code for nav lists start. Its a simple system that works for me. I have found when I don't do things like that I end up getting all screwed up.

Battlewax (http://www.waxingartistic.com/)

#24

"For CSS files, we are just beginning to adjust these to make them smaller. Instead of margin-left: xxpx; margin-right xxpx; we are starting to use: margin: 0px xxpx 0px xxpx;."

Actually "px" (or pt or em etc) is redundant when the value is "0" (zero)...

My 0.02 CHF: I go for hand-coding WITHOUT indent. Unless the html is very long I find this is cleaner (ugly line-wrapping with indented code!) and easier to read - I structure the code according to the content... Yes, everyone has their own taste when it comes to coding...

Thalwil (http://www.8ung.at/thalwil/)

#25

Why space HTML markup?
I cant think of a reason.
OK, occasionally I'll inherit some markup, strip the whitespace and then find it too hard to follow, so put some back in, just to understand the parenting, but this is the exception (and its usually horrid code)

Recently I inherited a project and one of the pages was 250K big. I kid you not. I stripped the white space and removed 100K without even trying. I couldnt beleive it.
Obviously, this is an extreme example, but I use white space in my markup when it adds something, not by default

Lea de Groot (http://viking.org.au/blog/)

#26

Formatting well the code can improve its understanding. It is also a step forward towards something that can repeated, and away from craftmanship.

Zelnox

#27

Zelnox -

Re: #26 - Is the move away from craftsmanship good or bad in your opinion?

Mark (http://www.lightpierce.com/ltshdw)

#28

A few comments from an outsider to the web design profession:
The HTML and CSS code that some of you think is worth protecting... it has value inasmuch as it delivers value to the website (to the website "mission", which is usually revenue to the owner, with user convenience being a means to that end - with lots and lots of exceptions of course).
The value of the literal code is much less, and some would posit not worth protecting.
Also: you *can* remove all white space and do some other obfuscating maneouvres (nice word, eh) *but* pretty-printers and their ilk have been with us since the sixties, so don't trust that method.
Moving away from craftmanship: kinda like what happens textiles: industrial methods *are* inevitable for large sites, anything driven by a database, e-commerce, b2b, etc., yet there will always be a space for "boutiques" like this here website and those other websites you admire so much.

Alexo (http://www.onconsultants.com)

#29

It seems web design becomes more and more of its own monster. Held to neither best practices for programming nor best practices for design, but programming has many concepts that can really improve every part of mark up.

An approach to html that uses modularity, scalability, and figuring out how to recycle code will only help your site to grow well and make coding it easier.

I have this fantasy of creating a new language for doing OO to create html where you would program ul.li.6("Home","Archive","etc") and get a nice list structure with preset naming convention so all you have to do is worry about your .css. Or div.body_text=link(url://www.com/body.txt) and you get your main body div that is linked to a text file of content.

Anyway, I'll keep dreaming.

Heath (http://wbmny.com)

#30

I have this fantasy of creating a new language for doing OO to create html where you would program ul.li.6("Home","Archive","etc") and get a nice list structure with preset naming convention so all you have to do is worry about your .css. Or div.body_text=link(url://www.com/body.txt) and you get your main body div that is linked to a text file of content.

The DOM does that quite nicely and is available for use in many programming languages. Just save your output after manipulating nodes and you have something very close to what you’ve been looking for.

Vinnie Garcia (http://blog.vinniegarcia.com)

#31

#26 "away from craftmanship": why? just because something can be repeated (and most people *will* adjust the design/code to fit their own purposes) doesn't mean moving away from craftmanship, in my opinion.

btw, i heavily comment any php stuff i write on my personal site, but the html and css is usally left alone. at work, there was absolutely no commenting done by previous web folk and it's a pain in the butt to fix anything - slowly i'm adding comments, but it'll take a while..

also, for the last few months, i've haven't done tabbing on any code i write, it just looks neater to me, and i also hate horizontal scrolling. yuck.

andrea (http://mellowtrouble.net)

#32

Have you considered the option, too, that many sites are dynamically generated, and that what amounts to very clean PHP code (or ASP, whatever) may end up looking like very ugly HTML after it's processed?

Erik J. Barzeski (http://nslog.com/)

#33

Absolutely right, Erik. Especially when you see sites that have very large chunks of whitespace (though that's more an issue for ColdFusion than PHP), or sites where things that have obviously looped are coded as one long line of code without spacing or line breaks between the code which comprises each line.

Basically, I don't care what my output code looks like, as long as it works. I don't have to look at it and neither does anyone else. Just browsers, and browsers don't care about whitespace (except inasmuch as it adds to or subtracts from the download time). It's my php/cf/jsp/templates/whatever that I'm working with when I do a site. There may be nicely formatted sections in the output, particularly if I'm using includes that are straight html or limited dynamic output, and there may be very ugly sections... but the code I'm working with will for the most part be clean and easy to read, if not commented nearly enough inline (usually write fusedocs for anything I do that other people need to see, though).

JC (http://http;//www.thelionsweb.com/weblog)

#34

I segment my CSS up into commented logical(ish) parts, list styles, link styles, form styles, whatever, if the cascade allows me the organizational privilege. That is for my own use, no one else's. LOL, not that people are faced with a law suit from borrowing the methods that I borrowed from someone else.

I do not indent page code, in school my teacher did not tell me to indent my sentences within paragraphs. hehe, if I did she would have thrown it at me along with a heavy chalk board wiper!

A lot of people do not code for the web dev communities better understanding of it, but as memory prompts......... ugh, I don't like long winded opinionated comments so I am gonna stop :-)

Gordon Mackay (http://www.gordonmac.com/)

#35

All I can say is that I absolutely hate code that is not indented / spaced "properly." I quote properly b/c I have seen very few people indent their code the way I do. I find that the indenting / spacing not only makes it easier for me to follow the flow of the code but also helps me to be sure I do things like close all my IF statements and LOOPs. commenting on the other hand I'm split on. I mean I comment to the extent that I may give a short 8 words or less description of what a block of code is supposed to do but I don't comment every single line of code or what every single variable is supposed to be used for. In that respect I of the opinion that if you can figure out whats going on in the code without a novel full of comments then you have no business looking at the code.

Cosmic

#36

I always format all my code. It makes it easier to find errors and understand the structure, whether it's HTML, CSS, or PHP. For HTML, I indent block elements (head, body, divs, paragraphs, lists, tables, etc...). For PHP, I indent anything within curly braces. I also make sure to add "\n" to the end of output lines to make the output readable. I usually only comment functions. I use four-column tabs for everything, and I can't stand anything else.

Brandon (http://www.radioactiverabbit.com)

#37

I indent my code, but when you view source you won't see any indenting. In fact it's all on one line. Why? Because for me, HTML is an object format, no different to an .exe or a .jar file. The source, on the other hand, is the commented, indented, modularised XSLT template.

IE barfs randomly at certain spacings. To reduce barfage, I reduce spaces. The stuff loads quicker too. If I need to debug, I switch indenting back on in the XSLT.

As for readability: if you need to read my HTML, feel free. It's not obfuscated. Run it through an HTML processor and indent it the way you want. Easy!

<vogon>What do you mean you don't have an HTML processor? For heaven's sake mankind! It's only a recursive parser, you know! I'm sorry, but if you can't be bothered to take an interest in Perl or Python or 6502 Assembler, that's your own look out! Energise the demolition beams!</vogon>

Eric TF Bat (http://flurf.net/)

#38

Didn't read all of the comments, but here's my views:

I indent my code by 2 spaces, not 4. I think 4 is a bit too much, and an overuse of white space.

I don't believe in protecting code. What is the point in protecting something, that a million other people already use or know about anyways? You learnt languages from viewing the source code and reading books, why should you prevent other people from doing the same?

Why not let people learn from what you do? If someone copies your code instead of learning from it, they're not exactly going to be a threat in later life to your profession are they? :P I don't exactly fear script kiddies.

As for comments: I don't comment my html code (unless there is reason to, which isn't often), I do however comment my php, perl etc etc.

[quote]The plural of CMS is CMSs [/quote]

I thought the plural of CMS would be CMS'

Nevermind.

Robert Lofthouse

#39

David, actually the plural of CMS's is not CMS's, CMSs or CMSes

It is infact CMS'

:)
Sorry for the off comment

Phil Dawson (http://afeditorials.resource-locator.com)

#40

Just taking a quick coffee break and wanted to post a hello