Loading...

Though handy, comments aren't the answer for everything.

woman staring at computer screen in annoyanceSure, comments can make it easier to understand the code you've built. The problem is, once designers know it's available, there's a tendency for them to start using comments all throughout their code. Eventually, abusing this feature causes code to actually look more cluttered, so it becomes a technique of diminishing returns. If someone else opens up your file, every time they run into a comment, they'll stop to read it, assuming it is important information. This can quickly turn an HTML file that can be viewed at a glance into a swamp of false alarms.

You can also assume that anyone that would need to work with your file is fluent in the code. There's no reason to add comments to explain what each line of code does—they'll already be able to understand most of it.

Another main reason to try and limit comment use is they can bog down loading times. While they aren't displayed after the code is parsed, the browser does have to read through each comment. If you wrote up a comment for every line of code, you'd be effectively doubling the size of your file, and the time it takes for the page to load.

The best way to keep the necessity for comments at a reasonable level is to write organized and elegant code from the start. We've been following certain practices with code writing—like each tag going on a new line, and indenting for nested items—because it makes the code more readable. The more readable your code is, the less reason there will be to explain it.

To help differentiate between ideal and trivial uses of comments, work through the activity below. Look at each code excerpt and decide if the use of comments is "helpful" or "unnecessary".

<!--Start of table-->
<table>
<tr>
<td>...</td>
Helpful

Unnecessary

Other people using your code probably won't need tags defined, so this comment wouldn't be needed.
Other people using your code probably won't need tags defined, so this comment wouldn't be needed.
<!--Company History panel-->
<h2>Our Story</h2>
<p>Our brand dates back to the start of...
Helpful

Unnecessary

Labeling the start of a specific section of your page can be useful to quickly see where relevant elements are in your code.
Labeling the start of a specific section of your page can be useful to quickly see where relevant elements are in your code.
<ul>
<li>...</li>
<li>...</li>
<li>...</li>
</ul><!--End of list-->
Helpful

Unnecessary

This is just one list, and pretty simple, so indicating the closing tag with a comment probably isn't necessary.
This is just one list, and pretty simple, so indicating the closing tag with a comment probably isn't necessary.
<ul>
<li>...
<ul>
<li>...</li>
<li>...
<ul>
<li>...</li>
<li>...</li>
</ul>
<!--End of list 3-->
</li>
</ul>
<!--End of list 2-->
</li>
<li>...</li>
<li>...</li>
</ul>
Helpful

Unnecessary

This one is more complicated, with a number of nested lists. Comments can make it easier to see which element is ending where.
This one is more complicated, with a number of nested lists. Comments can make it easier to see which element is ending where.
<!--<p>Para 1</p>-->
<p>Para 2</p>
<p>Para 3</p>
Helpful

Unnecessary

It can be useful to "comment out" elements to debug or to keep it from displaying until content is finalized.
It can be useful to "comment out" elements to debug or to keep it from displaying until content is finalized.
<!--Research Paper-->
<!--Introduction-->
<p>...</p>
<!--Findings-->
<p>...</p>
<!--My Conclusions-->
<p>...</p>
<!--Summary-->
<p>...</p>
Helpful

Unnecessary

There are more comments than elements in this example. This is too much, and it will bloat your code.
There are more comments than elements in this example. This is too much, and it will bloat your code.

Complete