Two small parts of HTML behave in ways people assume they understand and then get caught by. Comments are visible to anyone who looks, and whitespace is not discarded the way it appears to be. The second point in particular explains a layout gap that has consumed an enormous amount of collective debugging time.
Comment syntax
A comment opens with an angle bracket, an exclamation mark and two hyphens, and closes with two hyphens and a bracket. Anything between is skipped by the parser and never rendered.
<!-- Navigation begins here --> <!-- Multiple lines work fine. Useful for longer notes. --> The one syntax rule that bites is that comments cannot be nested. The first closing sequence ends the comment, so wrapping a block that already contains a comment leaves the remainder of that block exposed as live markup. If commenting out a section produces content that suddenly appears on the page, an inner comment is almost always the reason.
Avoid double hyphens inside comment text as well. They are not valid within a comment and older parsers handle them inconsistently.
Comments are not private
The comment is not stripped before the file is sent. It travels to the browser and sits in the page source where anyone can read it by pressing a key combination. Search engine crawlers download it too.
This means the head of the page is not a notebook. Do not leave passwords, internal addresses, database structure, unreleased pricing, notes about which client is difficult, or a link to an admin area that you assumed nobody would find. All of these have been discovered in production by people simply reading source. If a note must not be public, it belongs in a server side comment that gets processed away, or in your project documentation.
Using comments well
The comments that earn their place explain intent rather than restating markup. A comment saying a div opens here is noise, because the tag next to it already says that. A comment recording that a wrapper exists to work around a specific browser bug is genuinely valuable, because the next person will otherwise delete it and reintroduce the bug.
The one exception to the intent rule is marking the end of long nested blocks, which is a real readability aid on a complex page.
</div> <!-- /.product-grid --> </section> Whitespace collapses to a single space
Now the part that causes layout confusion. Consecutive spaces, tabs and line breaks in your markup are collapsed by the browser into one space character. Ten spaces between two words render as one, and a line break renders as a space rather than as a break.
<p>These words are spaced oddly.</p> That renders as a normal sentence with single spaces. It is what allows you to indent freely without affecting output, and it is why pressing return in your editor does not create a new line on screen. To force a line break you need the break element, and to preserve spacing exactly you need the preformatted element or the CSS white space property.
The gap between inline block elements
Collapsing to a single space rather than to nothing has one visible consequence. Inline and inline block elements are laid out like words in a sentence, so the whitespace between them in your source becomes a real space in the rendered line, typically around four pixels wide.
<span class="box">One</span> <span class="box">Two</span> Those boxes will not touch, and no amount of setting margin to zero will close the gap, because the gap is a text character rather than a margin. Three fixes work. Remove the whitespace by placing the closing and opening tags adjacent, which is ugly but effective. Set font size to zero on the parent and restore it on the children, which is a hack that still appears in older code. Or use Flexbox on the container, which removes the children from inline layout entirely and is the correct modern answer.
When you need whitespace preserved
Code samples and anything where alignment carries meaning need the preformatted element, which switches off collapsing entirely and keeps every space and line break exactly as written. The CSS white space property gives finer control, letting you preserve line breaks while still wrapping long lines, which is usually what you want for displayed output rather than for source code.
Format for humans
Because whitespace collapses, indentation costs you nothing in output and buys a great deal in readability. Indent one level per nesting level, keep a blank line between major sections, and let your editor format on save. The bytes are trivial, and any production build step will strip them anyway.