HTML Style Guide: Writing Clean and Maintainable Code

12 min read

Why HTML Style Matters

Consistent HTML coding style is crucial for maintaining large codebases and collaborating with other developers. A well-structured style guide ensures code readability, reduces errors, and makes maintenance easier. This guide covers essential HTML formatting rules and conventions that every web developer should follow.

Table of Contents

1. Basic Formatting Rules

Indentation and Spacing

<!-- Good Formatting -->
<div class="container">
    <header class="header">
        <nav class="navigation">
            <ul class="nav-list">
                <li><a href="/">Home</a></li>
                <li><a href="/about">About</a></li>
            </ul>
        </nav>
    </header>
</div>

<!-- Bad Formatting -->
<div class="container">
<header class="header">
<nav class="navigation">
<ul class="nav-list">
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
</header>
</div>

Key formatting rules:

  • Use 2 or 4 spaces for indentation (be consistent)
  • Add blank lines to separate large blocks of code
  • Keep line length under 80 characters when possible
  • Use soft tabs (spaces) instead of hard tabs

2. Naming Conventions

Class and ID Naming

<!-- Good Class Names -->
<div class="user-profile">
    <div class="profile-header">
        <img class="profile-avatar" src="avatar.jpg" alt="User Avatar">
        <h1 class="profile-name">John Doe</h1>
    </div>
    <div class="profile-content">
        <ul class="profile-stats">
            <li class="stats-item">Posts: 42</li>
            <li class="stats-item">Following: 123</li>
        </ul>
    </div>
</div>

<!-- Bad Class Names -->
<div class="up">
    <div class="ph">
        <img class="av" src="avatar.jpg" alt="User Avatar">
        <h1 class="n">John Doe</h1>
    </div>
    <div class="pc">
        <ul class="ps">
            <li class="si">Posts: 42</li>
            <li class="si">Following: 123</li>
        </ul>
    </div>
</div>

Naming guidelines:

  • Use lowercase for class and ID names
  • Separate words with hyphens (kebab-case)
  • Use descriptive, meaningful names
  • Keep names as short as possible while maintaining clarity
  • Use BEM methodology for component-based naming

3. File Structure

Document Organization

<!DOCTYPE html>
<html lang="en">
<head>
    <!-- Meta Tags -->
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="Page description">
    
    <!-- Title -->
    <title>Page Title</title>
    
    <!-- Stylesheets -->
    <link rel="stylesheet" href="main.css">
    <link rel="stylesheet" href="components.css">
    
    <!-- Scripts -->
    <script defer src="main.js"></script>
</head>
<body>
    <!-- Header -->
    <header>
        <!-- Navigation -->
        <nav>
            <!-- Nav content -->
        </nav>
    </header>

    <!-- Main Content -->
    <main>
        <!-- Page content -->
    </main>

    <!-- Footer -->
    <footer>
        <!-- Footer content -->
    </footer>
</body>
</html>

4. Attribute Order

Consistent Attribute Ordering

<!-- Recommended Attribute Order -->
<a
    id="main-link"
    class="link primary-link"
    href="/path"
    target="_blank"
    rel="noopener noreferrer"
    title="Link description"
    data-tracking="xyz"
>
    Link Text
</a>

<img
    id="hero-image"
    class="image hero"
    src="image.jpg"
    alt="Image description"
    width="800"
    height="600"
    loading="lazy"
    data-caption="Image caption"
>

<!-- Common Attribute Order -->
1. id
2. class
3. name
4. data-*
5. src, for, type, href, value
6. title, alt
7. role, aria-*
8. tabindex
9. style (if inline styling is necessary)

5. Comments and Documentation

Effective HTML Comments

<!-- Start: Header Section -->
<header class="site-header">
    <!-- Navigation Menu -->
    <nav class="main-nav">
        <!-- TODO: Add mobile menu toggle button -->
        <ul class="nav-list">
            <!-- Primary navigation items -->
            <li class="nav-item">...</li>
        </ul>
    </nav>
</header>
<!-- End: Header Section -->

<!-- 
    @Component: Product Card
    @Description: Displays product information in a grid layout
    @Dependencies: product-card.css, rating-stars.js
-->
<article class="product-card">
    <!-- Product Image -->
    <img class="product-image" src="..." alt="...">
    
    <!-- Product Details -->
    <div class="product-details">
        <!-- @TODO: Add price comparison feature -->
        <h2 class="product-title">...</h2>
        <p class="product-price">...</p>
    </div>
</article>

Comment guidelines:

  • Use clear, descriptive comments
  • Mark section starts and ends in large documents
  • Include component documentation
  • Note dependencies and requirements
  • Use TODO comments for future tasks
  • Keep comments updated with code changes

HTML Style Checklist

Formatting & Syntax

  • ✓Consistent indentation (2 or 4 spaces)
  • ✓Lower case element names
  • ✓Double quotes for attributes
  • ✓Proper closing tags
  • ✓No trailing whitespace

Organization & Structure

  • ✓Logical document structure
  • ✓Meaningful class names
  • ✓Proper section comments
  • ✓Consistent attribute order
  • ✓Clean file organization

Complete Code Examples

Well-Structured Component

<!-- 
    @Component: Featured Product Card
    @Description: Displays featured product with image, details, and CTA
    @Author: John Doe
    @Last Modified: 2024-11-18
-->
<article class="product-card product-card--featured">
    <!-- Product Header -->
    <header class="product-card__header">
        <img 
            class="product-card__image"
            src="product-image.jpg"
            alt="Detailed product description"
            width="400"
            height="300"
            loading="lazy"
        >
        <span class="product-card__badge">Featured</span>
    </header>

    <!-- Product Content -->
    <div class="product-card__content">
        <h2 class="product-card__title">
            Product Name
        </h2>
        
        <div class="product-card__details">
            <p class="product-card__price">$99.99</p>
            <div class="product-card__rating" 
                 data-rating="4.5">
                <!-- Rating stars here -->
            </div>
        </div>

        <p class="product-card__description">
            Detailed product description goes here...
        </p>
    </div>

    <!-- Product Footer -->
    <footer class="product-card__footer">
        <button 
            class="btn btn--primary product-card__cta"
            type="button"
            aria-label="Add Product Name to cart"
        >
            Add to Cart
        </button>
    </footer>
</article>

Style Guide Enforcement Tools

Code Formatters

  • Prettier
  • HTML Formatter
  • VS Code Extensions

Linters

  • HTMLHint
  • HTML Validator
  • ESLint HTML Plugin

Git Hooks

  • Pre-commit hooks
  • Husky
  • Lint-staged

Conclusion

Following a consistent HTML style guide is essential for maintaining clean, readable, and maintainable code. While specific rules may vary between teams and projects, the key is to establish and stick to clear conventions. Remember that good HTML style isn't just about aesthetics—it's about creating code that's easier to understand, debug, and maintain.

Keep your style guide updated as new HTML features and best practices emerge, and ensure your team is aligned on the conventions you choose to follow.

Ready to Clean Up Your HTML?

Try our HTML Formatter tool to automatically format your HTML code according to best practices and style guidelines.

Try HTML Formatter