Should You Document Your HTML?
Anyone who knows anything about my development style knows I’m a huge stickler for clean, semantic code. It kills me when a client asks me to edit an existing site that’s filled with improper tabs, run-on coding, extra blank lines and divs name “div45673435534″.
I’ve been so proud of the development community lately, because I’ve watched the importance of clean code in the past year or so become very, very important. As a matter of fact, clients are now becoming educated in this subject and hire developers based on the quality of their code.
So I’ve noticed several recent articles on structuring code, and since I’m always looking out for new ideas, I’ve perused as many as these articles as possible. However I’ve noticed one alarming tip that most of these articles offer up to developers – that you should comment your HTML extensively.
I disagree that you should comment your HTML extensively – or even at all.
Now, before you flame my comments let me explain why.
What is the purpose of commenting code?
Commenting code is meant to do a few things. One, it tells any future dev who needs to work on your site what something does. Two, it helps you find what you’re looking for.
In languages like PHP, Javascript, ASP and Objective C, commenting is very important because the files can go on for forever and it’s not always obvious as to what something does. HTML, however, is not and should not be built like this.
Semantics comes into play a lot more in HTML than anything else. What your HTML code does should always be obvious, as HTML itself is very simple in nature and structure. Your divs should be named semantically, header for the header, footer for the footer. Your files should never be very long, thanks to the use of includes and repeating areas (like the header and footer).
Properly tabbing and spacing your code also gives it natural breaks that allow your eye to quickly find each section. Comments are not needed for this.
Commenting The Close of Divs
Open any HTML or WordPress template from Themeforest and what do you see? Closed div tags that are commented. Why do you need to label which div is being closed if you properly tab? Commenting this just makes for an annoying longer file. For example, what’s really the purpose of this:
<div class="container">
<div class="header">
</div><!--header--->
</div><!---container--->Is that really necessary? Also putting comments like this blocks the eye from naturally discerning the short closed div tags.
Still with me?
If you’re a developer who’s worth anything at all your HTML should naturally be readable. I could possible see the need for a comment or two if you’re doing something extra wacky that may not make sense. But really, who’s not going to understand what a header div is for?
About the author
Amber Weinberg specializes in clean and semantic XHTML, CSS and WordPress development. She has over 10 years of coding experience and is pretty cool to work with. Amber is available for freelance work, so why not hire her for your next project?
While I agree that, in general, HTML code should not contain many comments – I disagree with you over commenting the closing DIV tags.
In many cases (WordPress is a great example), the opening and closing tags for a given code block are in different files… so the comments go a great way to helping the developer deliver clean code.
But like I said, in general comments shouldn’t be needed.
I was going to say the same thing about closing tags on different files. While this is not a best practice, it happens often, especially in WordPress.
I’m definetly with you on this one, comments on closing tags has saved me no end in time scanning through multiple files and long divs
I use multiple files, obviously, and have never had any problems with closed divs. I normally have one closed tag in the footer and it always belongs to container. Everything else closes in its own file.
Couldn’t agree more, Amber. I don’t comment my html – it just seems like a superfluous way to clutter up some otherwise clean code.
The only time when I’ve found html comments helpful is when I’ve been working on someone else’s code that has a long, long string of nested divs, so that you have to scroll to get from an opening tag to a closing tag (making it easy to lose track of which was which). Comments do come in handy then, but really – why have all those nested the first place?
I’m glad I’m not the only one who doesn’t like html comments
When it comes to WordPress or any other CMS I’d like to know where the tags open and close and comments help me quickly spot where a tag opens and closes. Of course I would not put a comment every time I open a new tag but on tags that open in one file but close in another file, I definitely like to put comments there. Or if there is a lot of back-end code mixed with front end code, then comments also help. It’s not necessary but I find it is much easier to develop.
I like your approach to semantic code. Would like to see an example of the way you think it should be without comments? The problem I see with not commenting is if multiple people start editing the site and not indenting properly, you don’t know where to start and begin. Also, I find when I’m scanning a large HTML file to find something, the comments break it up so I can tell where to look.
I do agree the closing comments are probably taking it too far – I don’t add them normally. Although they have come in handy when things are not indented properly!
I tend to do most of my commenting inside PHP. By the time the page hits the browser as HTML those comments are stripped. Other than conditional comments, the only HTML comment I see in my code at the moment serves to debug an RSS parser that usually returns nothing.
That being said, I don’t minify my HTML because if someone wants to view my source code I think they should be able to easily. My CSS and JS files are minified but start with a comment pointing people to the non-minified version, which are commented (not as well as I probably should).
But yeah, I agree. Well structured, semantic HTML should need only light commenting. The true value of documenting code comes into play in the other languages we use.
Amber,
I agree completely that proper code should by definition be clean and semantic by nature. I also agree that I have seen tons of code that I edit that was done by some previous to me that is depracated and a lot of times just a plain mess.
However, I disagree about commenting out closing div tags. The code I write is very clean and tabbed, yet often times when I work I find myself not only working from the top to the bottom, but sometimes from the bottom to the top of the code. By commenting out the closing div it serves as a quick reference point and overall doesn’t take up much virtual space.
With that being said there is no reason you have to comment out your closing div tag, but for me it is personal preference.
Well, it depends.
In WordPress themes, for example, it’s useful to know exactly where one div gets closed. This is because you may have a single page split into several .php files (index.php, header.php, single.php, footer.php… and even sidebars).
It’s very important to know precisely what div is being closed and indentation alone can cause all sorts of issues with different IDE softwares.
I use NetBeans. With mixed php/html source formatting, I need to comment like that.
It may be an IDE related issue but it’s always safer to “assume nothing”. Especially if you’re selling templates on websites like those.
Quick comments like those does not make any sense in a rendered page. True. But they will when you open the theme files in an IDE.
Obviously that’s the way I write code. Your mileage may vary if you’re a CSS frameworks fan and/or suffer from divitis
Niccolo I disagree. I mix PHP and HTML as well and almost all of my sites are in WordPress. If you need to comment which div is closing, you’re using too many divs and need to reduce the number,
I guess it’s a matter of personal preferences then.
In a footer.php file I’ve got open I have 3 divs closing. Still they’ve got comments because NetBeans cannot indent the code correctly.
There’s another issue with no comments on closing divs: editing long files on a small resolution device like a netbook or notebook.
I like to see those comments; know instantly what they are, even if they’re not indented correctly.
To each his own, I suppose.
Thanks for commenting.
I still disagree with commenting closed divs. Yes, most of my closed divs are in the footer, but there’s never more than 2 of them, so it’s obvious what each one is.
That being said, you should never have so many divs that you get lost in which one is closing, even if you can’t see the beginning of it. Developers should learn to make use of hooks other than div and get rid of the divitis
Isn’t it funny that most cases of divitis tend to occur among those “developers” converting from table-based layouts? It’s almost as if they have no understanding as to WHY you use certain tags… ;D
If you use a good piece of editing software you’ll see that those div’s will highlight the closing one when you click on the div id or class. No need for closing comments on the div’s.
I use Notepad++, supports plugins, ftp, and it’s FREE!
I have to agree. Commenting your HTML code seems to be taking things a bit far. If you write clean HTML code, commenting would seem to be unnecessary.
If only more coders were that diligent when it came to commenting their PHP code…
Love controversial posts
Anyways, on this one I will be sitting on the wire, as I *sometimes* comment my HTML if the file is getting a bit hairy (24 different accordions embedded within each other :S) so in that scenario you would need the commenting on ending div’s for easier reading. Otherwise I don’t bother, as it normally fits into one screen as most of the rest is done via the PHP and jQuery hooks
But good on you for bringing this up, as some people just love having a single file with PHP and HTML all in one place and you as future dev have to try and work with it …..
Awesome post here! Something that really causes lag-time for me is an outrageous amount of comments in standard framework. Not to say I do not appreciate it as I know it takes time, however, at the end of the project unless you delete it all you seem to be left with a ton of out of place comments that junk up your code and serve no purpose other than clutter.
Now, with this said I would actually prefer trigger happy code commenters’ when it comes to PHP, or dynamic segments of a website or system as these comments have gotten me out of binds more often than not.
100% agreed rarely use comments natural is better, a correct foundation in a structured html document doesn’t need it. I personally like using find and naming the divs correctly will make your coding even faster and easier to search in your development software/tools comments sometimes make it harder to search.
Its all based on your skills its not incorrect to use comments but universal coding is just better with standards and easier to work with.
I see there is another Mike so I am Mikey today…
I think indenting your markup is a better way of indicating where a div begins and ends (however, I picked this habit up from Python programming). I use Vim as my text editor and the autoindentation is generally pretty good and makes for very readable markup. I use comments liberally in JavaScript or server-side scripting languages, but I think they are often somewhat superfluous in HTML if you’re writing clean markup to start with.
Exactly my point ^_^ indention is a much better practice.
What about the best of both worlds? Comment the HTML, then strip and cache the resultant file for delivery at runtime.
The file sent to clients is nice and tiny & the file for developers is clear.
I wholly agree with this post except for the part about tabbing. Tabs don’t always translate well between editors, and so it is generally better to use spaces instead. PEAR standards actually call for using indents of 4 spaces (no tabs), but we drop it down to 2 in the Drupal world.
Agreed. Thank goodness I can set it as a option in GEdit in Linux
I’ve definitely suffered from the “too many divs” pitfall, and agree with you that there shouldn’t be more than 2 or 3 nested divs. However, I still fully believe in commenting closing tags. You say indenting will let you quickly find each section, but only if your section is less than…let’s see, on my screen…33 lines long, which is almost never the case for me (I like to spread my SQLs so THEY are more readable). Sure, if you store all the content within each div in to a separate PHP file, or minimize the lines, that problem is solved. But WHILE you’re developing the code inside each div, it’s immensely helpful to have that “do not cross over this line” mark.
There are my two cents. This is a brave post you put up, though.
Great article Amber. I have OCD for my coding, it has to be clean and has to be easy to read. I mainly program in Classic ASP and commenting at times is necessary to document the processes that are occurring in the page at runtime. I don’t tend to comment inside HTML documents however. I believe in easy id’s that help to document that specific part of the page e.g. id=”left_column” nothing like id=”style9836″ which tells you absolutely nothing. In ASP there are many loops and IF statements, etc.. These I help distinguish from the other parts of the code by indenting them, this helps considerably during the coding and debugging aspects of the development.
Great article, and your new office looks awesome from your pictures. I am jealous.
Keep Smiling…
I definitely agree with you. Commenting especially in the closing element tag is very important as there are times when opening and closing tags are separated across files or long lines as in WordPress theme files where I used to put wrapper div right below the body in header.php file and the closing one in footer.php.
Great article! Cheers =)
I agree with you. I was thinking about this just the other day. Sometimes you get code that comments when a div opens and comments when it closes. Just don’t think it’s needed unless you are a very novice coder. having said that you do need a good IDE that word wraps and indents nicely. EditPlus does the job for me.
I still think commenting on the beginning of major sections, such as header , content, footer is a big help.
Once your correctly indented HTML gets put into any kind of CMS the indentation gets completely screwed. If you view the source on this site for instance, you can see what WordPress has done to the correctly formed code. On top of that, if you add plugins that spit out their own HTML, it becomes even more of a mess.
So, I definitely think having comments makes it easier for other people trying to work on your site after you’ve built it and moved on. Don’t be too proud to help them out with a few comments!!
Paul,
Other developers working on a site, say this one for instance, will never view the source in the browser, so it doesn’t really matter how it looks online, just in the IDE. Also, you’ll never see the plugin or extra wordpress code in the actual theme files, so it doesn’t actually clutter up the site at all.
Hi Amber
Yes, if you are working directly on includes and templates that’s true.
The situations I’m thinking of, is 1) where you’re asked to create a new page for a site by viewing the source and copying it, then changing the image paths. Yes, it’s not a great way of doing things, but I’ve been made to do it on plenty of occasions! 2) When you’re scanning through the source to find something, comments help.
The point I’m trying to make is that it’s fine when you’re building a site from scratch in your own way and you’ve got everything indented nicely. But once a few other developers have gotten their hands on it and done it their own way things can get messy and that’s where sparingly commented code can help.
There’s nothing more painful than having to work with code that’s incorrectly indented and without comments. Better to have them than not to have them I feel.
I completely disagree. Commenting is necessary. There are always more than one person working on a big project (unless it’s just yourself, but even then). Commenting—yes even the div tags—is important. It’s easy to get lost and when it comes to time on making any changes in development it is important. Now the keyword here is development. When the site goes live and you’re concerned about every bit of information (or character strands) and time download, then you can removed said comments from the live site. But even then, we should kind enough to let people know how we do things, especially to up and coming HTML & coding developers. It makes it easier for them to see what we’ve done. It’s our responsibility. By the way, I’m not huge on coding, as I’m more of a designer, but none-the-less I do hand code everything I do even though I’d rather not at times.
Arlen,
If you write good HTML, there should not be a need for regular comments. If a developer can’t tell what you’re trying to do on the site by looking at the code, then you’re coding incorrectly.
I used to code C and other archaic languages ages ago (20 years—eek) and in school, nothing was ingrained more, regardless of markup languages or not, commenting is a good thing. It quickens any kind of changes. Everyone has their thing. You’ll find various people with their preferences, and like I said, if you’re really bent on not wanting to share your code or make it more difficult for others to follow your work, then by all means. So many people get into web markup languages without any real programming experience and have never taken a course on doing any kind of software development. So there are a series of mix messages that are out there. Commenting saves time, but you are correct a good developer can workout what’s going on, but why not save them the time?
Good article … couldn’t help but comment.
I’ll agree that you should definitely comment higher level languages (C/C++, Java, PHP, .NET, etc). But HTML is a whole other story. It’s easy to get confused and not be able to see what is going on with a higher level language. But that shouldn’t be the case with HTML. It simply is too simple of a language to have that issue.
At Alren, like Mike says below, it’s one thing (and a very bad practice) to not comment your PHP, C or other complicated programming language. HTML on the other hand, is completely different. There should never be a time that a dev can’t tell what’s a header, sidebar, wrapper or nav.
Great article.
I regard every comment I write as a failure to express myself in code. If something is too hard to comprehend, I refactor it and make it clean.
Robert C. Martin explains this excellently in his book “Clean Code” (see http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882/).
It is the most inspiring book I have read about software development.
I also tend not to comment HTML, with one exception: in a CMS template, I comment the beginning and end of each include file, and I also comment around any places where the CMS will be inserting content into the page. This is all to clarify where to look for problems when you (or someone coming after you) is looking at the source code.
One note about begin/end tags: I have found it an invaluable practice to NEVER close a tag in a different file than it started in. Each include file should be self-contained with all tags that were opened in it closing in it.
What ends up happening is that the main “template” contains the open/close html, head, and body tags, and some overall structural divs. Everything else is either in a self-contained include file, or self-contained content from the CMS.
Thus, any file, be it the main template, an include file, or CMS content, should be able to validate. This also keeps the overall site structure, structure of individual template components like body header, main menu, side menu, and footer, and the various content areas separated out, which tends to make them smaller and self-contained, for easier understandability.
Ahhh, so much fun to watch grown people argue over opinion. Like cleaner, sleeker code will get them laid, a raise, aor any notice at all… ever. Most people will never see it and it’s simply an electronic version of the good ol’ pissing contest. I’ve seen award winning sites with scrubby code, and vice versa. Lets all climb down off our horses and get over ourselves, there are no awards for clean code and quite frankly if a site looks good, no ones going to give a fuzzy rats ass.
Thinking the code isn’t important is the sign of someone who doesn’t know it well….You’re actually very much incorrect.
Clean code does matter – it matters in loading time, SEO, browser compatibility, the ability to be future proof and more. It’s true no one sees your code – until it’s broken. It’s also a sign of someone who knows their stuff. No one sees the insides of cars or machines, but if it breaks when it’s not supposed to, we suddenly do care what’s on the inside.
Also, if you want to work with any good company, you better care about code as they’ll determine to hire you or not based on it.