DEV Community

Drive Coding
Drive Coding

Posted on • Originally published at drivecoding.com

HTML Comments: 5 Mistakes That Ruin Your Code

#coding #webdev #html #beginners

TL;DR

HTML comments are one of the most underestimated tools in a beginner is toolkit. Most developers learn the syntax in five minutes and never think about it again. That is exactly why they keep making the same five mistakes that silently break their projects.

The Problem: You Think You Know HTML Comments

You have seen the syntax. You know it looks like this:

<!-- This is a comment -->
Enter fullscreen mode Exit fullscreen mode

You figured it out. Done. Moving on.

Except... not quite.

Here is the thing most beginners do not realize: HTML comments are not just invisible notes. They interact with your browser parser, your team is workflow, your page performance, and in some edge cases, even your site is security. Using them carelessly is like leaving sticky notes with your passwords on your monitor.

That old HTML file you opened last month that made zero sense? The one where you thought, what demon wrote this? That was you. Six months ago. With no comments.

Let is fix that.

What HTML Comments Actually Do

Before we get into mistakes, let is lock in the fundamentals.

HTML comments use this syntax:

<!-- Single line comment -->

<!--
  Multi-line comment.
  The browser ignores everything in here.
  Your users never see this.
-->
Enter fullscreen mode Exit fullscreen mode

When the browser hits <!--, it goes into ignore mode. Everything until --> is skipped completely. No rendering. No display. Nothing.

This makes comments incredibly powerful for three things:

  • Documentation — explaining why code exists
  • Debugging — temporarily disabling code without deleting it
  • Team communication — leaving context for other developers

But power without discipline creates chaos. Here are the five mistakes that turn helpful comments into a nightmare.

Mistake 1: Vague TODO Comments That Help Nobody

This is the most common HTML comment mistake beginners make.

<!-- TODO: fix this -->
Enter fullscreen mode Exit fullscreen mode

Fix what? Why is it broken? When did it break? Who broke it?

Future you will stare at this comment with the same blank face you give a math problem at 2am. It tells you nothing useful.

Do this instead:

<!-- TODO 2025-07-04: Button crashes on iOS Safari 16. Needs vendor prefix fix. Check caniuse.com/flexbox -->
Enter fullscreen mode Exit fullscreen mode

Specific. Dated. Actionable. That is a comment worth writing.

Mistake 2: Commenting Out Code and Forgetting It Forever

Disabling code with comments is a legitimate technique:

<!--
<nav class="experimental">
  New navigation - testing on staging only
</nav>
-->
Enter fullscreen mode Exit fullscreen mode

The mistake is leaving it there for six months with no explanation. Commented-out code with no context is just mystery garbage in your file.

Always add a reason and a deadline:

<!--
  DISABLED: New nav causes layout shift on mobile.
  Re-enable after CSS Grid audit is complete.
  Assigned: Sarah | Date: 2025-07-04
-->
Enter fullscreen mode Exit fullscreen mode

Mistake 3: Nesting Comments (This One Breaks Things)

This is a lesser-known gotcha that trips up even intermediate developers.

Nested HTML comments do not work the way you expect:

<!-- Outer comment
  <!-- Inner comment -->
  This line is NOW VISIBLE in the browser.
-->
Enter fullscreen mode Exit fullscreen mode

The browser reads the first --> it finds and considers the comment closed. Everything after that inner --> gets rendered as live HTML. Your hidden code is suddenly live on the page.

Never nest comments. It is not supported and the behavior is unpredictable across browsers.

Mistake 4: Putting Sensitive Information in Comments

This one can genuinely hurt you.

<!-- Admin login: user=admin pass=letmein123 -->
<!-- API endpoint: https://api.internal.com/secret-key=abc123 -->
Enter fullscreen mode Exit fullscreen mode

Comments are invisible to users but they are absolutely visible in the page source. Anyone who right-clicks and hits View Page Source can read every single comment you wrote. Credentials, internal URLs, system notes — all exposed.

Keep secrets out of HTML comments. Full stop.

Mistake 5: Over-Commenting the Obvious

There is a balance to commenting that most beginners miss. New developers often over-correct by commenting everything:

<!-- This is a paragraph -->
<p>Welcome to my website.</p>

<!-- This is a heading -->
<h1>About Me</h1>
Enter fullscreen mode Exit fullscreen mode

This adds noise without adding value. If the HTML tag already explains itself, the comment is just clutter. Save your comments for the non-obvious stuff — the workarounds, the business logic, the reasons why something is done a specific way.

Key Takeaways

  • HTML comments use <!-- --> syntax and are invisible to users but visible in page source
  • Always make TODO comments specific, dated, and actionable
  • Never nest comments — the parser will break in unexpected ways
  • Never store sensitive information in HTML comments
  • Comment the why, not the what — the code already shows what

These five mistakes cover the surface level, but there is one more dirty secret about HTML comments that most tutorials completely skip over — and it is the one most likely to embarrass you in a professional environment.

Want the complete guide with more examples? Read the full post at Drive Coding: https://drivecoding.com/html-comments-5-critical-mistakes-that-ruin-your-code-fix-now/

Originally published at Drive Coding

Top comments (0)