Beginner Tip:
Add Comments To Your Code

by Larisa Thomason,
Senior Web Analyst,
NetMechanic, Inc.

Designing a Web site is an all-consuming experience. For weeks - even months - you're constantly tinkering with your design, content, and code. You think you'll always remember every style definition and instantly know the purpose of every line of JavaScript code. But you won't. Unless of course, you've documented those decisions using comment tags!

Remind Yourself With Comments

Comment tags remind you why you included certain tags, style rules, or JavaScript functions. They make maintenance easier for you later. They're also invaluable to anyone who tries to maintain the site after you've designed it.

Have you ever tried to work with someone else's complex spreadsheet or database? It's not easy. And imagine how difficult it is if you're looking at someone else's complex page design!

When you fully document your code with comment tags, you're answering three questions (at least):

Comments don't display when a visitor looks at the Web page in a browser, but anyone who looks at the code can read them.

Identify Structure With HTML Comment Tags

Most pages in a Web site conform to a basic template design that creates a consistent look and feel for the site. The navigation menu displays in one spot, advertising in another, copyright information at the bottom.

Your main content section usually has the most prominent place on the page and it's generally your first stop when you need to update information on the page. You'll have an easier time if you've used comment tags to identify the major sections of the page.

HTML comment tags are easy to code:

Note the opening and closing characters. There shouldn't be any space between the opening tag, the exclamation point, and the two hyphens. There's also no space between the closing two hyphens and the closing tag.

Be careful if you're coding your page in a word processing program (like Microsoft Word) before transferring it to an HTML editor. Some word processors replace your hyphens and brackets with their own special characters. Turn that function off before you try to code HTML or you could get some really unexpected results on your page.

Answer the "where is it" question by noting the beginning and end of each major section of your page:

This makes it easier to find the section of code you need to edit. You're also less likely to accidentally stick some content into your navigation section or other inappropriate place!

CSS Comments Describe Formatting

Answer the second question "why did I do that" with CSS comments.

Style definitions can get pretty complicated. It's easy to get confused about a particular definition - especially when you're using an external style sheet to control formatting for an entire Web site.

Suppose you create a class that's only going to apply to a single page. It would be helpful to note which page it's used on and why. But for that, you need to use CSS comments, not HTML comments. Like this comment that describes how pull quotes on the home page will look:

/* Div for pull quotes on home page - yellow background, bold, green text, solid, 2px border */

Your CSS comments can be several lines long and as detailed as you need. Place them anywhere inside your opening and closing STYLE tags, but never inside a style rule.

You may also find CSS comments helpful when you're trying to debug your style definitions. Place comments around troublesome sections inside your style sheet and test the pages without those rules applied. That's a good way to isolate problems with inheritance or conflicting style rules.

Comment Your JavaScript

By far, the most common use for JavaScript comments is to hide JavaScript functions from older browsers that don't support JavaScript. However, as we noted in a June 2002 JavaScript Tip, new browsers may ignore your JavaScript because of those tags!

A better use of comment tags is to describe the purpose of a function, detail the variables, etc. JavaScript comment syntax is quite similar to HTML comment syntax. Like CSS comments, JavaScript comments must be placed inside the opening and closing SCRIPT tags:

Note the final two forward slashes. They're important! They keep the closing hyphens and bracket (-->) from being processed as part of the script. Be sure to always include them at the end of your JavaScript comment text.

Find Problems And Fix Them Easily

Any technique that makes maintenance easier will reduce coding errors - or at least make them easier to fix!

HTML comments help you quickly identify page sections so that you stay oriented inside your code. CSS comments remind you of the effect you wanted to achieve and help you isolate the problem. JavaScript comments tell you what the functions should be doing - even if they aren't performing like you expect.

But always remember to check your page with HTML Toolbox every time you make a change to the code. Even the simplest changes can create big problems. For instance, it's easy to accidentally delete a closing TABLE tag when you're adding and deleting content. Visitors using the Explorer browser won't notice any problem, but visitors using Netscape won't see your table at all!

HTML Toolbox scans your page for simple errors that have big consequences. It also alerts you to broken links and slow-loading pages.