Good Comments Make Good Html. Commenting makes HTML easier to write.

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:

- Makes your code easier to trouble shoot.

- Add a friendly reminder of things you wanted to include in your page.

- Allows you to save information about the page without showing the general public.

- 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:

<!-- Here is a comment! -->

Example of a multi-line comment:

<!-- I would like take this oppurtunity to descript the color of the sky.The color of the sky is a unique shade of the color blue.Unless of course there is overcast and then its more like gray.Then again in the fog evreything is white.Appearently the sky is multicolored! -->

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:

<!-- Start table 1 here - 3 rows high and 4 columns wide --><TABLE BORDER="1"><TR>...

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:

<!-- Table 1 - 4 rows high and 4 columns wide --><TABLE BORDER="1">    <TR>        <TD>            Cell 1-1        </TD>        <TD>            Cell 1-2        </TD>        <TD>            Cell 1-3        </TD>        <TD>            Cell 1-4        </TD>   </TR>   <TR>        <TD>            Cell 2-1        </TD>        <TD COLSPAN="2" ROWSPAN="2">            Cell 2-2        </TD>         <!-- Cell 2-3 would have been here -->        <TD>            Cell 2-3        </TD>    </TR>    <TR>       <TD>            Cell 3-1        </TD>         <!-- Cell 3-2 would have been here -->         <!-- Cell 3-3 would have been here -->        <TD>            Cell 3-4        </TD>    </TR>    <TR>       <TD>            Cell 4-1        </TD>        <TD>            Cell 4-2        </TD>        <TD>            Cell 4-3        </TD>        <TD>            Cell 4-4        </TD>   </TR></TABLE><!-- End table 1 here -->

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:

........<INPUT TYPE="TEXT" NAME="Var126" SIZE="25"> <!-- This is the 126th input variable for this form -->........

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:

<!-- Start Foo.com's Banner Code Here--><A HREF="http://forums.xisto.com/no_longer_exists/ SRC=="http://forums.xisto.com/no_longer_exists/404.png;-- End Foo.com's Banner Code Here --><!-- To Quit Losing Money Place Advertisement Here!;) --><H1><CENTER>My Title Here</CENTER></H1>

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

Example:

Fill in the form below to order your free money:<BR><!-- Use some of my money surplus to learn how to add an HTML form here! -->If you have any questions <A HREF="mailto:jdoe@foo.com">Email Me!</A><BR>

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

<FONT COLOR="RED">  <!-- Yellow font does not work here you already tried it three times! -->

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

Example:

<HTML>    <HEAD>        <TITLE>            My Title.        </TITLE>    </HEAD>    <BODY>        Body content here.    </BODY></HTML>

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:

<script LANGUAGE="JavaScript">    <!--     function foo() {        ...        ...    }    --></SCRIPT>

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:

<!-- Start Your JavaScript Here! -->    <script LANGUAGE="JavaScript">        <!--         function foo() {          ...          ...        }        -->    </SCRIPT><!-- End Your JavaScript Here! -->

Finally Place script comment in your scripts.

Example:

<!-- Start Your JavaScript Here! -->    <script LANGUAGE="JavaScript">        <!--         function foo() {     // Same Double Slash Comment Tag As In PHP!          ...          ...        }    // End Function Here!        -->    </SCRIPT><!-- End Your JavaScript Here! -->

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?

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?

<{POST_SNAPBACK}>

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

in fact, i think in php we gotta comment with // comments here
but im not sure if its in php.

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

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

<{POST_SNAPBACK}>

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

Although a lot of people are against validation, it makes us better at designing. By validating your website and routing out all of the errors, we can make better and more usable sites. Something that XML/XHTML was developed for.Vujsa, this is a very good thread. However, I believe you failed to mention WHY we put the contents of a script in comment tags. The answer is that older browsers (IE 3.0) may not be able to perform the actions of the script, and would display it as text. By putting it in comment tags, it is kept from displaying, but the browser still reads and processors the script.

Also, if you are using XHTML, be sure to read the documentation on how to do comments. In XHTML 1.0 Strict, putting HTML comments around code inside javascript tags is invalid, and will cause lack of validation. Instead, you need to use the CDATA comments.~Viz

I almost never use comments in html unless i want to make a comment for myself.. the output php shows me as html is usually different and stuff, i never watch it, only to make valid and clean in the making period, and later when everything runs smooth i never watch the source.. maybe it is due to my html is never being very complicated, i just see it with my eyes as a web browser but comments due help, even if it is said: "a real programmer does not need comments, the code is obvious to him" but sometimes the codes i wrote say a year back is not so understandable, that is why I started to write comments and another reason is because i might work with other people who will edit/write it too.

Although I don't comment my HTML like I should, and must admit that I pay the price later on...lol. Anyone who is just starting out should comment their HTML and any scripting/programing they do. As stated by Vujsa and others this helps with revisions later on, ALSO it helps when giving a friend a copy to look over when you need help troubleshooting a page or whatever so that they can tell at a glance what you were trying to do in a certin section without haveing to pull out a 5 lb. 4 ring binder full of coding notes to track down some obscure and rarely used, by the troubleshooter, bit of code

Although a lot of people are against validation, it makes us better at designing. By validating your website and routing out all of the errors, we can make better and more usable sites. Something that XML/XHTML was developed for.

 

Vujsa, this is a very good thread. However, I believe you failed to mention WHY we put the contents of a script in comment tags. The answer is that older browsers (IE 3.0) may not be able to perform the actions of the script, and would display it as text. By putting it in comment tags, it is kept from displaying, but the browser still reads and processors the script.

1064327950[/snapback]

Sorry vujsa, I failed to see that you did explain, in brief, why comment tags are used in <script> tags.