Code Comments & Style Guides: 3 Essential Rules

Stop Writing Code You’ll Hate in Six Months

Getting started with code comments and style guides is the best thing you can do for your future self. We’ve all been there. You open up an old project, and your own code stares back at you like a cryptic message from a past life. You see class names like .widget-alpha-2, a nesting of <div> tags so deep it’s dizzying, and that “brilliant” CSS hack you used to fix Internet Explorer. Now, it’s just a confusing relic. What was I even thinking?

This isn’t about being a bad coder. It’s about something we all skip: writing things down. In the rush to build and launch, taking time to add code comments or write a style guide feels like the boring homework you can put off forever.

But “future you” is the one who gets that homework. Or it’s the new teammate who just joined, terrified to touch your spaghetti code because they have no idea how it works. Raw, undocumented code is a locked door. Code comments are the key under the mat. A style guide is the floor plan taped to the wall.

This isn’t about creating extra work. It’s about being kind to yourself and your colleagues. It’s about turning a one-time project into something that can actually be fixed, updated, and understood later. Let’s stop leaving secret puzzles and start building things that make sense with proper code comments and style guides.

Why Bother with Code Comments and Style Guides?

You might think your code is obvious. It’s almost never obvious. Here’s what actually happens when you write things down:

• You Save the “Why”: Code tells you what is happening. Code comments tell you why. Why that aria-label? Why position: absolute there? The “why” vanishes from your memory faster than anything, and it’s the most important part to get back.
• You Save Your Team Weeks: A new developer can spend days lost in your codebase, or an hour reading a clear style guide and well-commented examples. Good documentation is the fastest onboarding tool you have.
• You Stop Endless Debates: “Should we use dashes or underscores?” “Tabs or spaces?” A style guide ends the discussion. It’s the rulebook. This means everyone’s code looks and works the same way, so you can jump into any file without getting whiplash.
• You Prevent Bugs: A comment that says, “Warning: Changing this padding breaks the mobile menu,” stops someone (often you) from accidentally breaking it later. A TODO comment flags temporary work so it doesn’t become permanent.

Writing Code Comments That Don’t Stink (HTML & CSS)

Comments aren’t for stating the obvious. Saying <!-- this is a div --> is just noise. They’re for capturing the reasoning you’ll forget.

HTML Comments: Explain Your Decisions
Good code comments explain your choices, especially for accessibility or complex structures.

html

<!-- GOOD: It tells you the *reasoning* -->
<!-- Main site nav. 'aria-label' distinguishes it from a footer nav if we add one later. -->
<nav aria-label="Primary" class="c-primary-nav">
    <!-- This button is hidden on desktop but stays for screen readers and mobile toggle -->
    <button class="c-nav__toggle" aria-expanded="false" aria-controls="nav-menu">Menu</button>
    <ul id="nav-menu" class="c-nav__menu">
        ...
    </ul>
</nav>

<!-- BAD: Just adds clutter -->
<div class="container"> <!-- container div -->
    <header> <!-- page header -->
        <h1>Hello</h1> <!-- main title -->
    </header>
</div>

Quick HTML Comment Tips:

• Bookmark Big Sections: In a huge template, drop a simple landmark.

html

<!-- START: Product Gallery -->
<!-- END: Newsletter Signup -->

• Flag Temporary Code: Be honest about shortcuts.

html

<!-- TODO: Replace with proper SVG sprite when assets are final (Task #101) -->
<!-- FIXME: This inline style is a hotfix for the checkout page only -->

CSS Comments: Tell the Story
CSS files need a narrative. Group rules for a component and explain the tricky bits.

css

/* GOOD: Groups and explains a whole component */
/* ============================================
   PRIMARY BUTTON (.c-btn)
   The main button style for calls-to-action.
   Modifiers: --small, --secondary
   ============================================ */
.c-btn {
    display: inline-flex;
    align-items: center;
    padding: 0.75rem 1.5rem;
    border-radius: 0.375rem;
    /* Using 'currentColor' lets the border theme automatically */
    border: 2px solid currentColor;
    font-weight: 600;
}

.c-btn--secondary {
    /* Inverts colors for less prominent actions */
    background-color: transparent;
    color: var(--color-primary);
}

/* BAD: What is this for? Why these numbers? */
.blue-box {
    padding: 15px;
    margin: 10px;
    background: blue;
}

Quick CSS Comment Tips:

• Make a Table of Contents: For a big stylesheet, start with a map.css/* CONTENTS: * 1. Variables (Colors, Fonts) * 2. Reset / Base Styles * 3. Layout Grid * 4. Components * 5. Utility Helpers */
• Use Visual Separators: A line of = or - makes it easy to spot where one component’s styles end and another’s begin.
• Explain the Weird Stuff: That calc() function, the negative margin, the z-index stack, explain why they’re there.

Creating a Style Guide That People Actually Use

A style guide isn’t a dusty manual. It’s your team’s playbook. The best ones are living documents, sometimes even built from the real code.

What to Put in Your HTML/CSS Style Guide:

1. The Nitty-Gritty Rules:
   • “We indent with 2 spaces, never tabs.”
   • “Use double quotes in HTML, single quotes in CSS.”
   • “Always add the closing slash to self closing tags in our JSX/Vue templates.”
2. Naming Stuff:
   • “We use a BEM-like system: .block__element--modifier.”
   • “Classes just for JavaScript hooks start with .js- and we promise not to style them.”
   • “Utility classes for one-off things start with .u- (like .u-hidden).”
3. HTML Principles:
   • “Use the right tag for the job. A button should be a <button>, not a <div>.”
   • “Every image must have an alt attribute. If it’s decorative, use alt=\"\".”
   • “Follow basic accessibility practices, we use the WAI-ARIA Authoring Practices guide as a reference.”
4. How We Organize CSS:
   • “We write mobile first. Our media queries add complexity for larger screens.”
   • “We use CSS Custom Properties (variables) for all colors and spacing.”
   • “Our file structure is: settings (variables), tools (mixins), base, components, utilities.”
5. The Golden Part: The Component Library:
   This is a visual catalog. For a button, card, or modal, you show:
   • What it looks like (the actual component).
   • The HTML to copy (the approved markup).
   • The CSS that styles it.
   • Notes: “Use the --secondary mod for less important actions,” or “This needs an aria-label if the text is just an icon.”

How Code Comments and Style Guides Work in Real Life

Let’s say you’re building a media-card component.

1. Check the Style Guide. It says: use BEM naming, put CSS in /components, and ensure it’s keyboard accessible.

2. Write the HTML with helpful code comments.

html

<!--
MEDIA CARD
Used for article previews in grids and sidebars.
Variant: Add '--featured' class for a larger, highlighted version.
-->
<article class="c-media-card">
    <div class="c-media-card__image-wrap">
        <!-- Aspect-ratio container to prevent page jump on load -->
        <img class="c-media-card__image" alt="..." loading="lazy">
    </div>
    <div class="c-media-card__body">
        <h3 class="c-media-card__title">...</h3>
        <!-- Text truncation is handled by CSS 'line-clamp' -->
        <p class="c-media-card__excerpt">...</p>
        <a class="c-media-card__link c-btn c-btn--small" href="...">Read More</a>
    </div>
</article>

3. Write the CSS as a clear block.

css

/* ============================================
   MEDIA CARD COMPONENT (.c-media-card)
   ============================================ */
.c-media-card {
    border: 1px solid var(--color-border);
    /* Creates uniform spacing in a grid layout */
    margin-bottom: var(--spacing-unit);
}

.c-media-card__image-wrap {
    /* Classic 16:9 aspect-ratio box */
    position: relative;
    padding-bottom: 56.25%; /* (9 / 16) * 100% */
    overflow: hidden;
}

/* TODO: Respect prefers-reduced-motion here */
.c-media-card__link {
    transition: transform 0.2s ease-out;
}

4. Add it to the Living Style Guide. Now it’s documented, and anyone on the team can use it the right way, every time. For more on structuring CSS at scale, resources like CSS Guidelines offer excellent foundational advice.

The Bottom Line: Be an Architect, Not a Gardener

Writing code without documentation is like being a gardener who plants beautiful flowers but never labels them. You might remember what they are this season, but next year? It’s a mystery.

Code comments and a style guide are your labels and garden map. They turn your work from a personal, temporary sketch into a professional, lasting system. They trade confusion for clarity and secret knowledge for shared understanding.

You don’t have to do it all at once. Start with your next component. Explain one tricky CSS rule. Write down one team agreement. The reward isn’t the minute you write it down, it’s the countless hours in the future, for you and your team, where a moment of frustration becomes a moment of instant “aha!” That’s how you build things that last.

New to HTML? Start Here: HTML Tutorial for Beginners: Your Complete Introduction to HTML Basics

[INSERT_ELEMENTOR id=”122″]