Writing Clean HTML

Writing Clean HTML

Clean HTML is organized, readable, consistent, and written so that another developer can understand the document without having to untangle unnecessary or confusing markup.

Browsers can often display poorly formatted HTML, but that does not make the markup easy to maintain. Good coding habits reduce mistakes, simplify troubleshooting, and make future changes much easier.

Use Consistent Formatting

Choose a formatting style and use it consistently throughout the website. Consistency makes patterns easier to recognize and helps developers find mistakes more quickly.

<section>
  <h2>Our Services</h2>
  <p>Learn more about the services we provide.</p>
</section>

Changing indentation styles, spacing rules, or markup patterns from one part of a document to another makes the source harder to scan even when the browser displays the page correctly.

Indent Nested Elements

Indent child elements so the nesting and relationships between elements can be seen immediately.

<nav>
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about.html">About</a></li>
    <li><a href="/contact.html">Contact</a></li>
  </ul>
</nav>

Poor indentation can hide missing closing tags or incorrect nesting. A consistent indentation style makes the document structure much easier to follow.

Use Lowercase HTML

HTML element and attribute names are commonly written in lowercase. Using lowercase consistently makes markup easier to read and avoids unnecessary variations in coding style.

<img src="/img/photo.jpg" alt="HTML image example">

Avoid mixing capitalization styles without a reason.

<IMG SRC="/img/photo.jpg" ALT="HTML image example">

Although HTML parsing is generally case-insensitive for element and attribute names in HTML documents, lowercase markup has become the normal convention and provides a clean, predictable style.

Quote Attribute Values

Some HTML attribute values can technically be written without quotation marks, but consistently quoting values makes the markup clearer and avoids problems when values contain spaces or other characters.

<a href="/contact.html" title="Contact Us">Contact</a>

Choose either double or single quotation marks and use the style consistently. Double quotation marks are commonly used in HTML.

Use Semantic HTML

Use HTML elements according to the meaning and purpose of the content rather than choosing elements only for their default appearance.

<article>
  <h2>Website Maintenance</h2>
  <p>Regular maintenance helps keep a website current and dependable.</p>
</article>

Elements such as header, nav, main, article, section, and footer can communicate document structure more clearly than using generic containers for everything.

Semantic markup can also provide useful structure for browsers, assistive technologies, search engines, and developers maintaining the page.

Avoid Unnecessary Markup

Do not add elements when they provide no structural, semantic, scripting, or styling purpose.

<div>
  <div>
    <div>
      <p>Our office is open Monday through Friday.</p>
    </div>
  </div>
</div>

If the extra containers serve no purpose, the same content can be written more simply.

<p>Our office is open Monday through Friday.</p>

Extra markup increases document complexity and can make CSS, JavaScript, accessibility, and future maintenance more difficult than necessary.

Use Meaningful Names

Choose class and ID names that describe the purpose or meaning of the element rather than relying only on its current appearance or position.

<section class="product-details">
  ...
</section>

A name such as product-details remains understandable even if the design changes later. Names such as blue-box or left-column can become misleading when the appearance or layout changes.

Meaningful names also make CSS and JavaScript easier to understand because the relationship between the markup and the code that uses it is clearer.

Use Comments Carefully

HTML comments can help explain important sections or unusual decisions in the source code.

<!-- Main site navigation -->
<nav>
  ...
</nav>

Comments should explain something useful rather than repeat what the markup already makes obvious.

<!-- Paragraph -->
<p>Welcome to our website.</p>

Outdated comments can be more confusing than having no comment at all, so comments should be maintained along with the code they describe.

Keep HTML, CSS, and JavaScript Organized

HTML should primarily describe content and document structure, CSS should control presentation, and JavaScript should provide behavior and interaction.

<link rel="stylesheet" href="/css/style.css">
<script src="/js/main.js" defer></script>

Small demonstrations may place CSS or JavaScript directly in an HTML document, but larger websites are generally easier to maintain when reusable styles and scripts are kept in appropriately organized files.

Separating responsibilities also makes it easier to modify the design or behavior without unnecessarily changing the underlying HTML content.

Maintain a Consistent Document Structure

Use a predictable structure for HTML documents so important information can be located quickly.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Page Title</title>
  </head>
  <body>
    <header>
      ...
    </header>

    <main>
      ...
    </main>

    <footer>
      ...
    </footer>
  </body>
</html>

A consistent document pattern becomes especially valuable when maintaining many pages because developers do not need to relearn the basic organization of every file.

Clean HTML Example

The following example uses clear indentation, semantic elements, descriptive names, quoted attributes, and a simple document structure.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Web Design Services</title>
  </head>
  <body>
    <header>
      <h1>Example Web Design</h1>

      <nav aria-label="Main navigation">
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/services/">Services</a></li>
          <li><a href="/contact/">Contact</a></li>
        </ul>
      </nav>
    </header>

    <main>
      <section class="services">
        <h2>Our Services</h2>
        <p>We create responsive websites for businesses and organizations.</p>
      </section>
    </main>

    <footer>
      <p>Example website.</p>
    </footer>
  </body>
</html>

Clean code does not require every developer to format HTML identically. What matters most is that the chosen conventions are logical, readable, and applied consistently throughout the project.

Common Clean Code Mistakes

Best Practices

• Use consistent formatting throughout the website.
• Indent nested elements so document structure is easy to see.
• Write HTML element and attribute names in lowercase.
• Quote attribute values consistently.
• Use semantic elements that describe the purpose of the content.
• Avoid unnecessary elements and excessive nesting.
• Choose meaningful class and ID names.
• Use comments only when they add useful information.
• Remove obsolete and unused markup instead of leaving clutter behind.
• Keep HTML, CSS, and JavaScript responsibilities organized.
• Use a predictable document structure across similar pages.
• Choose coding conventions once and apply them consistently throughout the project.

Summary

Clean HTML is easier to read, troubleshoot, modify, and share with other developers. Consistent formatting, logical indentation, semantic elements, meaningful names, useful comments, and simple markup all contribute to code that remains understandable as a website grows.

Browsers may tolerate messy markup, but maintainable websites benefit from disciplined coding habits. Next, we will look at HTML Validation and how validation tools can identify markup errors and standards-related problems.