by Larisa Thomason,
Senior Web Analyst,
Remind Yourself With Comments
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):
- Where is it?
- Why did I do that?
- What does this code do?
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:
<!-- insert comment here -->
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:
<!-- Begin navigation here -->
code for navigation menu
<!-- End navigation -->
<!-- Begin main content section here -->
code for main content
<!-- End main content section -->
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.
<!-- Countdown function: days until the class reunion // -->
Find Problems And Fix Them Easily
Any technique that makes maintenance easier will reduce coding errors - or at least make them easier to fix!
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.