Good Comments Make Good Html.

vujsa

Feb 24 2005, 01:03 AM

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:

CODE

Example with a comment:

CODE

Example of a multi-line comment:

CODE

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:

CODE

<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:
Click to view attachment
Comments will help you keep track of where cells used to be.
Example:

CODE

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

<TD>
Cell 2-3
</TD>
</TR>
<TR>
<TD>
Cell 3-1
</TD>


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

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:

CODE

........
<INPUT TYPE="TEXT" NAME="Var126" SIZE="25"> 
........

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:

CODE

<A HREF="http://www.foo.com/foo_sale.html"><IMG SRC=="http://www.foo.com/foo_sale.gif"></A>




<H1><CENTER>My Title Here</CENTER></H1>

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

CODE

Fill in the form below to order your free money:<BR>


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:

CODE

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

CODE

<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

miCRoSCoPiC^eaRthLinG

Feb 24 2005, 11:17 AM

cool.. good followup on that Commented Coding article.

vujsa

Feb 25 2005, 04:06 AM

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:

CODE

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:

CODE

<script LANGUAGE="JavaScript">

</SCRIPT>

Finally Place script comment in your scripts.
Example:

CODE

<script LANGUAGE="JavaScript">

</SCRIPT>

Happy coding,

vujsa

jcguy

Feb 25 2005, 12:54 PM

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:



works in php and perl too?

vujsa

Feb 25 2005, 10:51 PM

QUOTE(jcguy @ Feb 25 2005, 07:54 AM)

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

Spog

Mar 13 2005, 03:58 AM

QUOTE(vujsa @ Feb 25 2005, 06:51 PM)

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

vujsa

Mar 16 2005, 12:22 AM

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

ChronicLoser

Mar 16 2005, 12:42 AM

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 ^_^

moonwitch

Mar 16 2005, 03:22 AM

QUOTE(vujsa @ Feb 24 2005, 02:03 AM)

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

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!

h3lium

Aug 10 2005, 07:07 PM

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

Latest Entries

minnieadkins

Oct 31 2005, 06:48 PM

Comments make the code. HTML comments aren't very widely used, but they do help, especially if you plan on modifying your layout in the future. It's also a good practice to comment the end of your functions (php, c++, java, etc) and the beginning to display what they actually do. While loops, foreach loops, if statements all pose a threat of error. All it takes is overlooking that one little '}' and there you have it. ERROR. Good advice on the comments, although I personally think you can have too many comments. Keep it informative and direct. Don't make half your document comments. =/

For a nice free text editor, I recommend HTMLKit from Chami. When you put in your javascript it automatically puts in the comment to keep older browsers from reading your script. It's a very nice editor, and very customizable. Lots of plugins for php as well. I recently used notepad++ and it's pretty good for all kinds of languages, and you can minimize your blocks effectively.

twitch

Oct 31 2005, 04:40 AM

QUOTE(guy @ Oct 29 2005, 07:04 PM)

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.

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

Logan Deathbringer

Oct 31 2005, 03:17 AM

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

Quatrux

Oct 30 2005, 10:47 PM

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.

vizskywalker

Oct 30 2005, 09:25 PM

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

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

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

Latest Entries