Practical Exercise 14: HTML Comments
Learn how to use HTML comments to document your code, facilitate its maintenance, and improve collaboration among developers. This practical exercise is ideal for beginners.
Activity
Add comments to an HTML document.
Interactive Solution
Solution with complete HTML code
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8" />
<title>Comentarios</title>
</head>
<body>
<!-- Este es un comentario en HTML -->
<p>Este párrafo está visible.</p>
<!-- <p>Este párrafo está comentado y no se verá.</p> -->
</body>
</html>
Variants of the Same Exercise
Variant 1: Documenting Code Sections
As your HTML grows, comments help other developers (or your future self) quickly understand the document structure.
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8" />
<title>Documented Website</title>
<!-- SEO meta tags for social media -->
<meta property="og:title" content="My Website" />
<meta property="og:description" content="Learning HTML with practical exercises." />
<!-- Main stylesheet -->
<link rel="stylesheet" href="css/estilos.css" />
</head>
<body>
<!-- ==================== HEADER ==================== -->
<header>
<h1>My Website</h1>
<nav>
<!-- Main navigation menu -->
<a href="/">Home</a>
<a href="/servicios">Services</a>
<a href="/contacto">Contact</a>
</nav>
</header>
<!-- ==================== MAIN CONTENT ==================== -->
<main>
<section>
<!-- Introduction section -->
<h2>Welcome</h2>
<p>This is an example site for practicing HTML.</p>
</section>
<section>
<!-- Features section - pending completion -->
<h2>Features</h2>
<p>Coming soon...</p>
</section>
</main>
<!-- ==================== FOOTER ==================== -->
<footer>
<!-- Copyright info and legal links -->
<p>© 2026 My Website. All rights reserved.</p>
</footer>
</body>
</html>
Section comments (with ====) work as visual markers. They're especially useful in long HTML files where you need to quickly identify blocks while scrolling.
Variant 2: Multi-line Comments for Design Decisions
Sometimes you need to explain why you made a certain technical decision. Multi-line comments are ideal for this type of documentation.
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8" />
<title>Design Decisions</title>
<!--
We're using inline CSS instead of an external file
for this prototype. When we move to production,
we'll move these styles to estilos.css.
Decision made: 06/10/2026 by the frontend team.
-->
<style>
body {
font-family: Arial, sans-serif;
line-height: 1.6;
background-color: #fafafa;
}
.alerta {
padding: 15px;
border-left: 4px solid #ff9800;
background: #fff3e0;
}
</style>
</head>
<body>
<!--
TODO: Replace sample content with real data
when the content team delivers the final copy.
Estimated deadline: 06/17/2026.
-->
<div class="alerta">
<strong>⚠️ Notice:</strong> This page is under construction.
</div>
<h1>Landing Page Prototype</h1>
<p>
This is sample content that will be replaced during
the project's final implementation phase.
</p>
<!--
Testimonials section temporarily commented out.
We're not deleting the code because we'll need it
in the next iteration (Sprint 3).
-->
<!--
<section class="testimonios">
<h2>What Our Clients Say</h2>
<blockquote>
<p>Excellent service, highly recommended.</p>
<cite>— Juan Pérez</cite>
</blockquote>
</section>
-->
</body>
</html>
Best practices for decision comments:
- Include the date and author of each important decision
- Use
TODOto mark pending tasks (many editors highlight them automatically) - When temporarily commenting out code, explain why and when it will be restored
Variant 3: Comments for Debugging
One of the most common techniques during development is commenting and uncommenting code to identify problems. This is known as "isolation debugging."
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8" />
<title>Debugging with Comments</title>
</head>
<body>
<h1>Test Page</h1>
<!-- Paragraph 1 works correctly -->
<p>This is paragraph 1. It displays without issues.</p>
<!-- Paragraph 2 is commented out to test if it causes a conflict -->
<!-- <p>This is paragraph 2. Commented out for debugging.</p> -->
<!--
Paragraph 3 was disabled because the link to Google
was causing a CORS error in the development environment.
It will be restored when we configure the proxy.
-->
<!--
<p>
Find more information on
<a href="https://www.google.com" target="_blank">Google</a>
</p>
-->
<p>This is paragraph 4. It works perfectly.</p>
<!-- End of test page -->
</body>
</html>
This technique allows you to isolate problematic sections without deleting code. If the problem disappears when you comment out a block, you've found the culprit.
Variant 4: Conditional Comments for Browsers (Historical)
Before HTML5 standardization, Internet Explorer conditional comments were used to load specific code depending on the browser version. Although they're not used today, it's important to know about them if you work with legacy sites.
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8" />
<title>Legacy Compatibility</title>
<!-- Stylesheet for modern browsers -->
<link rel="stylesheet" href="css/moderno.css" />
<!--[if IE 9]>
<link rel="stylesheet" href="css/ie9.css" />
<![endif]-->
<!--[if lt IE 9]>
<p class="alerta-antigua">
You're using an outdated browser.
<a href="https://browsehappy.com">Update it here</a>.
</p>
<script src="js/html5shiv.min.js"></script>
<![endif]-->
</head>
<body>
<h1>Website</h1>
<p>
Conditional comments were only interpreted by
Internet Explorer 9 and below. Modern browsers
treat them as normal comments (they ignore them).
</p>
</body>
</html>
Important note: Conditional comments stopped working in Internet Explorer 10 and above. Today, the recommended approach is to use feature detection with JavaScript (Modernizr or @supports in CSS) and define a mobile-first strategy with meta viewport.
Best Practices and Common Mistakes
| ✅ Best Practice | ❌ Common Mistake |
|---|---|
Document code sections (<!-- header -->) | Leave commented-out code without explanation for months |
Use TODO to mark pending tasks with a date | Comment out sensitive information (passwords, tokens, private URLs) |
| Explain complex technical decisions in comments | Over-comment code that is already self-explanatory |
| Temporarily comment out blocks for debugging | Push debugging comments to production |
Use section comments (====) in long files | Nest comments (<!-- <!-- --> -->) — doesn't work, the first --> closes everything |
| Delete unnecessary code instead of commenting it out | Use IE conditional comments in new projects |
Frequently Asked Questions (FAQ)
Do HTML comments affect page performance?
Minimally. Comments increase the HTML file size (a few bytes each). On sites with thousands of comments, there might be a marginal difference in download time, but in practice it's not a problem. The browser ignores them when rendering, so they don't affect display speed.
Can comments be seen from the browser?
Yes. Anyone can see your HTML comments by inspecting the source code (Ctrl+U or right-click → View page source). Never include sensitive information like passwords, API tokens, database table names, internal IP addresses, or confidential business logic in comments.
Can I nest comments in HTML?
No. HTML doesn't support nested comments. The first --> that appears after <!-- closes the comment, regardless of how many additional <!-- there are. If you need to "comment out a comment," you'll have to delete or modify the original comment.
Should I comment my HTML code if I use Git?
Yes, but with a different purpose. Git records the change history (who, when, and why something was modified). Code comments document the current state (what this section does, why this decision was made). They're complementary: the commit message explains the change, the comment explains the resulting code.
💡 Comments are a communication tool between developers (including your future self). A good comment doesn't say what the code does (the HTML already says that), but why it does it that way. Learn more about best practices in Basic Structure of an HTML Document.