Improve Site Performance Increase Site Traffic Monitor Site Uptime Webmaster Resources NetMechanic Home Looking For Help? Partner Programs Privacy Policy Contact Us Press Room
NetMechanic Home LOGIN | HELP | ABOUT US | PRODUCTS | SITE MAP
NetMechanic Menu
Over 52 Million Web Pages Tested!     
 
Positioning tips.
search engine optimization story search.
Search for:


Your Email:

I would like to receive my newsletter in:
HTML format
Text format


Increase traffic.
Volume 8 (2005)
   September
   June
   April
   March
   January

Volume 7 (2004)
   November
   September
   July
   June
   May
   April
   March
   February (Part 2)
   February
   January (Part 2)
   January

Volume 6 (2003)
   December
   November (Part 2)
   November
   September
   August (Part 2)
   August
   July (Part 2)
   July
   June (Part 2)
   June
   May (Part 2)
   May
   April (Part 2)
   April
   March (Part 2)
   March
   February (Part 2)
   February
   January (Part 2)
   January

Volume 5 (2002)
   December (Part 2)
   December
   November (Part 2)
   November
   October (Part 2)
   October
   September (Part 2)
   September
   August (Part 2)
   August
   July (Part 2)
   July
   June (Part2)
   June
   May (Part 2)
   May
   April (Part 2)
   April
   March (Part 2)
   March
   February (Part 2)
   February
   January (Part 2)
   January

Volume 4 (2001)
   December (Part 2)
   December
   November (Part 2)
   November
   October (Part 2)
   October
   September (Part 2)
   September
   August (Part 2)
   August
   July (Part 2)
   July
   June (Part 2)
   June
   May (Part 2)
   May
   April (Part 2)
   April
   March (Part 2)
   March
   February (Part 2)
   February
   January (Part 2)
   January

Volume 3 (2000)
   December (Part 2)
   December
   November (Part 2)
   November
   October (Part 2)
   October
   September (Part 2)
   September
   August (Part 2)
   August
   July (Part 2)
   July
   June
   May
   April
   March
   February
   January

Volume 2 (1999)
   December
   November
   October
   September
   July
   June
   May
   April
   March
   February
   January

Volume 1 (1998)
   December
   November
   October
   September

 

Beginner Tip:
Add Comments To Your Code

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

  
September 2003
Vol. 6, No. 17
 • Promotion Tip
 • Usability Tip
 • Beginner Tip
  

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

  1. Where is it?
  2. Why did I do that?
  3. 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.

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:

<script type="text/javascript" language="javascript">
<!-- Countdown function: days until the class reunion // -->

    JavaScript function here

</script>

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.



Rate This Tip:
Not Useful Useful Very Useful   
 
NetMechanic Tools
HTML Toolbox
Browser Photo
Server Check
Search Engine Starter
Search Engine Tools
GIFBot
Newsletter
HTML Tutorial and Tips
Search Engine Tutorial
Accessibility Information
Browser Problem Tutorial

Company Info
Products
About Us
Contact
Advertise
Link To Us
Jobs
Privacy Policy
Partner Programs
Press Room
RSS Feed
Support
 



Powered by Overture!

 
     
 
   
 
     


Keynote Home
Copyright © 1996-2007,
Keynote NetMechanic
All rights reserved.