HTML Comments and Formatting Rules

Learn how to write comments in HTML and follow formatting conventions that keep markup readable and maintainable.

Beyond just writing tags that work, professional HTML also needs to be readable — for you later, and for anyone else who works on the same code. Comments and consistent formatting make that possible.

Writing comments

HTML comments use the syntax <!-- comment text -->. Anything between <!-- and --> is completely ignored by the browser — it is never rendered on the page and never affects behavior. Comments can span a single line or multiple lines.

Comments are useful for leaving notes for yourself or teammates: explaining why a section exists, temporarily disabling a block of markup during development, or marking sections of a long file so they're easier to navigate.

Indentation conventions

Although HTML does not require any particular indentation to work correctly, consistent indentation is a strong convention that makes nested structure easy to see at a glance. The typical rule is: each time an element nests inside another, indent its content by one consistent unit (commonly two or four spaces).

Without indentation, deeply nested markup becomes very hard to read and debug, because it's difficult to tell which closing tag belongs to which opening tag just by looking at the flat text.

Whitespace handling

Browsers collapse extra whitespace in HTML content: multiple spaces, tabs, and line breaks in your source code are all rendered as a single space. This is why you can freely indent and format your HTML source code for readability without it affecting how the page actually looks — the browser doesn't preserve the exact whitespace you typed, only meaningful single spaces between words.

Valid nesting and naming conventions

Beyond indentation, maintainable HTML follows a few more habits: tags must be properly nested (never overlapping), tag and attribute names are written in lowercase, attribute values are quoted consistently (double quotes by convention), and values for attributes like class and id use readable, descriptive names (e.g. class="main-navigation" rather than class="mn1").

These conventions don't change how the browser renders the page — they exist purely for humans: making the file easier to read, debug, and extend months or years later, and easier for other developers to collaborate on.

Comment syntax

Comments always start with <!-- and end with -->. Content inside a comment is never rendered and never executed. Comments cannot be nested inside other comments.

<!-- This is a single-line comment -->

<!--
  This is a
  multi-line comment
-->

<!-- <p>This paragraph is temporarily disabled</p> -->

Code Examples

A simple comment explaining the purpose of the heading that follows it. Expected result: Just the heading "SampleApp" is visible; the comment text never appears anywhere in the browser.

The comment line is completely invisible in the rendered page — only "SampleApp" appears on screen.

A well-formatted document using consistent 4-space indentation to reflect the nesting depth of each element — <header> and <main> are indented one level inside <body>, and <h1> is indented one level further inside <header>. Expected result: A page with a header showing "SampleApp" and a main section titled "Courses" with descriptive text — visually identical to a version with no indentation at all, since whitespace formatting doesn't affect rendering. Even though this extra whitespace and indentation has zero effect on the rendered page, it dramatically improves how easy the file is to read and maintain.

Each level of nesting is indented consistently, making it easy to visually trace which tags belong inside which parent.

<!-- Main page heading -->
<h1>SampleApp</h1>

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>SampleApp</title>
</head>
<body>
    <header>
        <h1>SampleApp</h1>
    </header>

    <main>
        <section>
            <h2>Courses</h2>
            <p>Browse by engineering branch.</p>
        </section>
    </main>
</body>
</html>

Whitespace collapsing

Browsers ignore extra whitespace in HTML source, collapsing runs of spaces, tabs, and line breaks into a single space between words.

Source code:
  <p>Hello        world

     friend</p>

Rendered output:
  Hello world friend

(multiple spaces and line breaks all collapse into single spaces)

Important Rules

Comments use <!-- ... --> and are completely invisible in the rendered page.

Comments cannot be nested inside other comments.

Indent nested elements consistently (commonly 2 or 4 spaces) to reflect the document's structure visually.

Browsers collapse multiple spaces, tabs, and line breaks in HTML source into a single rendered space.

Use lowercase tag/attribute names and descriptive, readable values for class and id to keep markup maintainable.

Where this shows up

Large production codebases — like the HTML templates behind e-commerce sites or content management systems — rely heavily on comments to mark section boundaries (e.g. <!-- START footer --> ... <!-- END footer -->) and consistent indentation so that teams of developers can navigate thousands of lines of markup without getting lost.

<!-- outer comment <!-- inner comment --> still outer? --> <!-- outer comment (inner note written as plain text, not another comment) -->

HTML comments cannot be nested. The parser treats the first --> it finds as the end of the comment, so anything after it (like "still outer? -->") is rendered as literal visible text, not hidden.

Overlapping tags (where <span> closes after its parent <p> has already closed) produce invalid, unpredictable markup — closing tags must always close in the reverse order their matching opening tags appeared.

[Predict the Output] What will a visitor actually see rendered on the page from this HTML? <p>Hello <!-- greeting --> World</p> A. Hello <!-- greeting --> World B. Hello World C. Hello World (with the comment text hidden but the extra spaces preserved exactly) D. An error, because comments cannot appear inside a paragraph

B. Hello World — The comment is completely stripped from the rendered output, and the browser collapses the remaining whitespace around it into a single space, producing "Hello World". Comments can legally appear inside most elements, including paragraphs, and never cause an error.

Take this unformatted, uncommented HTML and rewrite it with proper indentation and a comment explaining what the section is for: <section><h2>Pricing</h2><p>Choose a plan.</p></section>

<!-- Pricing section --> <section> <h2>Pricing</h2> <p>Choose a plan.</p> </section>

Add a comment above the <section> tag, then indent <h2> and <p> one level inside it.