Documenting your code
HTML comments let you leave notes in your source code that the browser ignores. They won’t change how a page looks, but they make your markup easier to read, debug, and hand over to someone else.
What are HTML comments?
Comments are annotations in the code that are not displayed in the browser. They help you and others understand what your code is doing, why it’s doing it, and anything else worth remembering.
Basic syntax
The syntax is straightforward:
<!-- This is a comment -->Everything between <!-- and --> is ignored by the browser.
Why comment your code?
Clarity and context
Comments can explain what a section of code is for, especially when it isn’t obvious at a glance. That helps when you come back to your own work after a few months, or when someone else needs to pick it up.
Debugging
Commenting out sections of HTML is a common debugging trick. It lets you isolate part of the page to see where a problem is coming from.
<!-- <p>This paragraph is causing issues.</p> -->Collaboration
In a team, comments can flag instructions or explain decisions so the next person doesn’t have to guess.
Best practices
Be clear and concise
A good comment says what it needs to say and stops. If you need a paragraph to explain one line, the markup might be the real problem.
Avoid overcommenting
Too many comments clutter the file and make it harder to scan. Comment the bits that are complex or non-obvious, not every single tag.
Use comments to section off code
Comments work well as signposts when a page gets long:
<!-- Header section -->
<header>...</header>
<!-- Main content section -->
<main>...</main>
<!-- Footer section -->
<footer>...</footer>Update comments when code changes
Outdated comments are worse than no comments at all. If you change the markup, update or remove the note that goes with it.
Types of comments
Descriptive comments
A short description of what a block of code does:
<!-- Initialise main navigation -->
<nav>...</nav>To-do comments
Mark tasks to come back to:
<!-- ToDo: Add accessibility tags to navigation links -->Commented-out code
Useful for temporarily disabling markup while you work:
<!--
<p>This section is under review.</p>
-->Commenting for SEO
Comments can hold notes about SEO choices – why certain keywords appear, or reminders to optimise images and metadata. Search engines ignore comment text, so this is for you, not Google.
<!-- SEO: Optimised keywords for local search -->Comments and maintenance
On a large or complex page, comments act as a map. They save time when you need to find and update a specific section months later.
Comments for learning and teaching
If you’re learning HTML or showing someone else how it works, comments in the markup can explain how and why a particular element is used.
Comments and version control
In a Git project, comments in the HTML can complement your commit messages by explaining intent at the point where the markup lives.
Comments won’t show on the page, but they make the code behind it easier to work with. Use them where they earn their keep – and keep them up to date.