Code Comments

Comments are notes in your code that the browser ignores. They help you (and others) understand what the code is doing — and more importantly, why.

HTML Comments

<!-- This is an HTML comment -->

Use comments in HTML to label major sections so you can find your way around the file:

<!-- Header: site title and navigation -->
<header>
  <h1>My Article</h1>
</header>

<!-- Main content -->
<main>
  <article>
    ...
  </article>
</main>

<!-- Footer: attribution and AI disclosure -->
<footer>
  ...
</footer>

CSS Comments

/* This is a CSS comment */

Use comments in CSS to group related rules and explain non-obvious choices:

/* === Typography === */
body {
  font-family: 'Georgia', serif;
  line-height: 1.6; /* 1.5–1.7 is a common range for readability */
}

/* === Layout === */
main {
  max-width: 680px;
  margin: 0 auto; /* centers the content block on the page */
}

/* === Colors === */
:root {
  --color-accent: #2563eb; /* chosen to meet WCAG contrast on white */
}

What to Comment (and What Not To)

Comments should explain why, not just repeat what the code already says.

Skip it — the code is self-explanatory:

/* Set color to red */
color: red;

Worth adding — the reasoning isn't obvious:

color: red; /* matches brand color from client style guide */

A good rule of thumb: if you had to stop and think about why something works the way it does, add a comment. If the code speaks for itself, leave it alone.