Comments can make it easier to understand the code you've built, but sometimes designers overuse comments. Overuse of comments causes code to look more cluttered, which defeats the purpose of adding comments in the first place.
For example: If someone else is reviewing your code, each time they run into a comment, they'll stop to read it. They assume it is important information. If you overuse comments or include unimportant information in them, your reviewer will become impatient. To save time, they may skip or simply not read some comments, which could lead to them missing some needed information.
Additionally, excessive commenting can slow the time it takes for a page to display in a browser. Even though comments aren't displayed after the code is parsed, the browser does have to read through each comment to determine its function. If you wrote a comment for every line of code, you'd double the size of your file, and the time it takes for the page to load would increase.
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 need there is to explain it in a comment. It’s safe to assume that anyone viewing your source file is fluent in the code. With that in mind, limiting your comments to truly helpful information is considered best practice.
To 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.
Which one?
<table><!-- Start of Table -->
<tbody><!-- Start of Table Body -->
<tr><!-- Start of Table Row -->
<td>...</td>
<td>...</td>
</tr><!-- End of Table Row -->
</tbody><!-- End of Table Body -->
</table><!-- End of Table -->
Comments shouldn't be used to define each line of code. This practice is considered excessive and unnecessary.
Comments shouldn't be used to define each line of code. This practice is considered excessive and unnecessary.
<!--Company History-->
<h3>About Us</h3>
<p>Our company has had strong roots in
the community since 1935...</p>
Labeling the start of a specific section can be useful to quickly scan through large amounts of content. This type of comment is helpful.
Labeling the start of a specific section can be useful to quickly scan through large amounts of content. This type of comment is helpful.
<ol>
<li>Preheat oven...</li>
<li>Mix ingredients...</li>
<li>Bake..</li>
<li>Let cool..</li>
</ol><!--End of Ordered List-->
If you have one simple list, indicating the closing tag with a comment isn't necessary.
If you have one simple list, indicating the closing tag with a comment isn't necessary.
<ul>
<li>Dogs
<ul>
<li>Breed</li>
<li>Behavior</li>
<li>Diet</li>
<li>Personality</li>
</ul><!--End Dogs List-->
</li><!--End Dogs Category-->
<li>Cats
<ul>
<li>Breed</li>
<li>Behavior</li>
<li>Diet</li>
<li>Personality</li>
</ul><!--End Cat List-->
</li><!--End Cat Category-->
<li>Birds
<ul>
<li>Breed</li>
<li>Behavior</li>
<li>Diet</li>
<li>Personality</li>
</ul><!--End Bird List-->
</li><!--End Bird Category-->
</ul>
This one is more complicated, with several nested lists. Comments can make it easier to see which element is ending where.
This one is more complicated, with several nested lists. Comments can make it easier to see which element is ending where.
<p>Fill out the following form to complete your registration process.</p>
<!--<form>
...
<button type="submit">Submit Form</button>
</form>-->
It can be useful to "comment out" elements to debug or to keep content from displaying until it is finalized.
It can be useful to "comment out" elements to debug or to keep content from displaying until it is finalized.
<!--Research Paper-->
<!--Introduction Paragraph-->
<p>...</p>
<!--Findings Paragraph-->
<p>...</p>
<!--Conclusion Paragraph-->
<p>...</p>
<!--Summary Paragraph-->
<p>...</p>
<!--END Research Paper-->
There are more comments than elements in this example. This is too much, and it will bloat your code. This type of commenting is unnecessary.
There are more comments than elements in this example. This is too much, and it will bloat your code. This type of commenting is unnecessary.
You got # out of # correct. Click the Retry button for another attempt.
You got a perfect score. Great job!
