HTML Style Guide

29 March 2025 | Category: HTML

Creating clean, consistent, and well-structured HTML code is essential for readability, maintainability, and performance. A good HTML style guide ensures that your code is easy to read for both humans and machines, while also improving collaboration in teams.

1. General Formatting Rules

1.1 Use Proper Indentation

Use 2 spaces or 4 spaces for indentation (avoid tabs).
Nest elements properly to reflect their hierarchy.

<!-- Good -->
<div>
    <p>Hello, World!</p>
</div>

<!-- Bad -->
<div>
<p>Hello, World!</p>
</div>

1.2 Lowercase for Tags and Attributes

Use lowercase for HTML tags, attributes, and file names.

<!-- Good -->
<img src="image.jpg" alt="Description">

<!-- Bad -->
<IMG SRC="image.jpg" ALT="Description">

1.3 Close All Tags

Even for elements like <img> or <input>, use a self-closing slash (/) in XHTML-based setups or leave it open for HTML5.

<!-- Good -->
<img src="image.jpg" alt="Description">

<!-- XHTML -->
<img src="image.jpg" alt="Description" />

1.4 Use Double Quotes for Attributes

Always wrap attribute values in double quotes ("), not single quotes.

<!-- Good -->
<a href="https://example.com" title="Visit Example">Example</a>

<!-- Bad -->
<a href='https://example.com' title='Visit Example'>Example</a>

1.5 Write Semantic HTML

Use semantic elements like <header>, <footer>, <section>, and <article> instead of <div> for better readability and SEO.

<!-- Good -->
<header>
    <h1>Welcome to My Website</h1>
</header>

<!-- Bad -->
<div>
    <h1>Welcome to My Website</h1>
</div>

2. Structuring HTML

2.1 Use a Consistent Doctype

Always start with the HTML5 doctype for modern browsers.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
</head>
<body>
</body>
</html>

2.2 Organize the `<head>` Section

Keep metadata, styles, and scripts well-organized in the <head> section.
Place custom CSS before JavaScript files.

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Page Title</title>
    <link rel="stylesheet" href="styles.css">
    <script src="script.js" defer></script>
</head>

2.3 Comment Code When Necessary

Add comments to explain complex sections of code.
Use descriptive comments.

<!-- Main Navigation -->
<nav>
    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
    </ul>
</nav>

2.4 Keep Line Length Short

Limit each line of HTML code to 80-100 characters for better readability.

<!-- Good -->
<a href="https://example.com" title="Visit Example Website">
    Example Website
</a>

<!-- Bad -->
<a href="https://example.com" title="Visit Example Website">Example Website</a>

3. Attribute Best Practices

3.1 Omit Unnecessary Attributes

Use default attributes only when necessary.

<!-- Good -->
<input type="text">

<!-- Bad -->
<input type="text" value="">

3.2 Use Accessible Attributes

Always add alt attributes to images for accessibility.
Use aria-* attributes where necessary for assistive technologies.

<img src="image.jpg" alt="A description of the image">
<button aria-label="Search">🔍</button>

3.3 Avoid Inline Styles

Use external or internal CSS instead of inline styles.

<!-- Good -->
<div class="highlight">Highlighted Text</div>

<!-- Bad -->
<div style="background-color: yellow;">Highlighted Text</div>

4. File and Folder Structure

4.1 Use Logical Folder Names

Organize assets like CSS, JS, and images into separate folders.

project/
├── css/
│   └── styles.css
├── js/
│   └── script.js
├── images/
│   └── logo.png
└── index.html

4.2 Use Descriptive File Names

File names should be lowercase and use hyphens for separation.
Avoid special characters or spaces.

Good: my-website-logo.png
Bad: MyWebsiteLogo.PNG

5. Accessibility and SEO

5.1 Add Descriptive Titles

Use a clear and concise <title> tag for SEO and user navigation.

<title>Learn HTML: A Beginner's Guide</title>

5.2 Use Proper Headings

Use headings (<h1> to <h6>) in a logical hierarchy.

<h1>Main Title</h1>
<h2>Subheading</h2>
<h3>Another Subheading</h3>

5.3 Add `lang` Attribute

Specify the language of the document for better accessibility.

<html lang="en">

5.4 Use Descriptive Links

Avoid vague text like “Click Here.” Use meaningful link text instead.

<!-- Good -->
<a href="/about">Learn more about us</a>

<!-- Bad -->
<a href="/about">Click Here</a>

6. Performance Optimization

6.1 Minimize File Sizes

Compress images and minify CSS/JavaScript files.

6.2 Use `defer` or `async` for Scripts

Improve page load speed by deferring JavaScript execution.

<script src="script.js" defer></script>

6.3 Use a Content Delivery Network (CDN)

Load external libraries (e.g., Bootstrap, jQuery) from a CDN for faster delivery.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css">

7. Example of Clean HTML Code

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="A beginner's guide to writing clean and maintainable HTML code.">
    <title>HTML Style Guide</title>
    <link rel="stylesheet" href="styles.css">
    <script src="script.js" defer></script>
</head>
<body>
    <header>
        <h1>Welcome to the HTML Style Guide</h1>
    </header>

    <main>
        <section>
            <h2>Why Use a Style Guide?</h2>
            <p>Using a consistent style guide ensures that your code is easy to read, maintain, and collaborate on.</p>
        </section>
    </main>

    <footer>
        <p>&copy; 2025 Your Company</p>
    </footer>
</body>
</html>

Conclusion

A consistent HTML style guide improves your development workflow, ensures better collaboration, and results in maintainable and accessible web projects. By following these best practices, you’ll write clean, professional HTML code every time!