Good Comments Make Good HTML.
Commenting makes HTML easier to write.
This is a spin off from another article I wrote entitle Good Comments Make Good Scripts. While the code is different, the concepts for comment are the same.
Enjoy!

Disclaimer!
This tutorial is intended to be used to show the benefites of commenting your HTML in order to write clean, easy to read code. For the purpose of this tutorial, HTML, XML, XHTML validating is not taken into consideration. While I will make an effort to point out non-standardized code, validation has never been my priority and I'll probably miss a few things. Always run your HTML through an HTML validater to check for compatability issues.

Reasons for commenting HTML:
    [/tab]- Makes your code easier to trouble shoot.
[tab]- Add a friendly reminder of things you wanted to include in your page.
    [/tab]- Allows you to save information about the page without showing the general public.
[tab]- Provides a way of giving yourself credit for creating a nice page.
    - Used as instructions for JavaScript and other client side script usage.

Getting Started!
-------------------------------------------------------------------
An HTML comment tag is quite simple, everything inside the tag is hidden from the browser and is considered to be the comment.
The HTML comment tag is:


Example with a comment:


Example of a multi-line comment:


Now lets talk about when and where to comment yout HTML.

The first place I like to add a comment in a web page is at the beginning of a table.
Example:


Another really good use for a comment in a table is when a cell spans multiple rows or columns.
Say that you have a table that is 4 rows and 4 columns and you want one really large cell in the middle.
Attachment:

Comments will help you keep track of where cells used to be.
Example:

I use this frequently as I tend to get confused when I start spanning cells.

Occasionally I have very lengthy forms that I need to comment in order to keep track of what's what.
Example:


Comments are great for saving places for all of our content.
For example, say you have an advertiser with a banner and just below his banner you have room for one more banner, just comment that this is where you can place a new add.
Example:


This works great for code you don't know how to write yet as well.
Example:


Okay here's an example of what didn't work:


Another method I use to help keep track of the flow of HTML is indenting.
Example:


See how easy it is to check if all of your closing tags are present.
This is great if you have tables inside of tables, but will always make reading the code a lot easier.

You may have noticed that all of my tags use uppercase type. I have found that this makes picking the tags out from all of the content text much easier. When I learned HTML, tags were always like this but now validation requires lowercase type as I understand it. You will have to decide for yourself how best to write your code but I suggest that you keep in mind the possibility that someday you may need to convert your HTML to another markup language.

Tells us about your suggestions for commenting.

Happy coding,
vujsa

cool.. good followup on that Commented Coding article.

Something I touched on breifly in this article but doesn't warrant its own tutorial is commenting client side scripting.

I'll specify JavaScript.

To begin with, you should place your JavaScripts inside an HTML comment tag.
Example:
This is done to hide the script from browsers that don't support JavaScript. The practice of hiding the script is fast becoming pointless due to the fact that any decent web browser is JavaScript capable. I suggest that you continue hiding the code until Microsoft Windows is provided free to everyone.

Next Place HTML comments around your scripts.
Example:


Finally Place script comment in your scripts.
Example:


Happy coding,
vujsa

Can commenting in the coding be done in php and perl scripts as well? I remembered vaguely that it can be done in php and perl scripts, but I think the way of commenting will be different. Does this code:

<!-- commenting -->

works in php and perl too?

Actually, I wrote another topic just for that. I have a link at the beginning of this tutorial.

Here it is again:
Good Comments Make Good Scripts.
This is specifically for PHP but Perl is touch on as well.

Happy coding,
vujsa

Actually, php allows multiple comment tags.

All of the following comment tags work in php:
// JavaScript single line comment tag.
/* JavaScript multiple line comment tag. */
# Shell style comment tag.

See Also -> Good Comments Make Good Scripts.

vujsa

hmm...i agree that comments are useful in html...but I think it's much more important in scripting (example: java, javascript, php, etc, etc). With html, it usually doesn't get so convoluted to a point where you absolutely need/require comments and such...

but I completely agree with you, vujsa. Comments do make things simpler ^_^

I used to write my html in uppercase all the time as well, for the same reason you've just touched. To find the actual code easier BUT I've now switched to lowercase, not because of the validation (heh, I hardly ever use it ) but because xml (and I think XHTML) both require lowercase tags.

My biggest help in writing HTML is basically good indentation. It's one of my pet peeves, to look at horrid code with crappy indentation. For example, someone did write the code in notepad, but prefered "Times New Roman" as font because it looked better than Courier, and they used tab. It will look horrible in code when you do use a fixed width font. I have to admit it, I don't use Courier, but I do use another fixed width font for coding (ProggyCleanTT or Anonymous I think)

Anyhow, good tutorial vujsa!

for simple pages, i always find it easier to not use comments, because they usually don't amount to much, but for larger complex projects that involve a lot of coding, commenting is essential for later revisions and modifications