Learning HTML - Writing Clean, Maintainable HTML

#Introduction

The code you write today will be read next month — by yourself or a teammate. Episode 19 covers practices for writing clean, maintainable HTML: consistent indentation, choosing elements based on meaning, a logical heading hierarchy, clear class naming, and automated linting.

Tidy HTML reduces bugs, speeds up finding elements, and makes the document flow easy to understand. A little discipline up front saves a lot of time later.

#Structure and Indentation

#Consistent Indentation

Two spaces per level is the common standard. Every element goes one level deeper inside its parent:

Two-space indentation

<main>
  <section>
    <h2>Artikel Terbaru</h2>
    <article>
      <h3>Judul Artikel</h3>
      <p>Ringkasan artikel dalam satu paragraf.</p>
    </article>
  </section>
</main>

Don't mix tabs and spaces in one project. Uniform rules make git diffs cleaner and changes easier to trace.

#Limiting Nesting Depth

The deeper elements nest, the harder they are to read. If you pass four or five levels, consider breaking the structure up:

Avoid deep nesting

<div>
  <div>
    <div>
      <div>
        <p>Terlalu dalam dan sulit dirawat.</p>
      </div>
    </div>
  </div>
</div>

The example above uses four divs without meaning. Replace them with semantic elements or restructure to keep things concise.

#Semantic Markup

#Choose Elements by Meaning

Every element carries meaning. Use article for self-contained content, section for themed groups, aside for supplements, and nav for navigation — not div for everything.

Elements by meaning

<article>
  <h2>Tips Belajar HTML</h2>
  <p>Pelajari dasarnya dulu, baru pola lanjutan.</p>
  <aside>
    <p>Tahukah kalian: article adalah konten yang bisa berdiri sendiri.</p>
  </aside>
</article>

Content that will later be placed on other pages, like blog posts or news, fits article. Keep div and span for truly neutral wrappers.

#A Logical Heading Hierarchy

One h1 per page, then continue in order without skipping. Headings are both the document skeleton and a navigation map for screen readers:

Heading hierarchy

<h1>Belajar HTML</h1>
<section>
  <h2>Struktur Dokumen</h2>
  <h3>Elemen Semantik</h3>
  <h3>Praktik Terbaik</h3>
</section>

Jumping from h2 straight to h4 confuses screen reader users. Keep it tidy like a table of contents, not like random text.

#Attributes and Naming

#Attribute Order and Consistency

Set an attribute writing order — for example id, class, then other attributes — so code is quick to scan:

Attribute order

<a id="tautan-beranda" class="tautan" href="/beranda">Beranda</a>
<img src="foto.png" alt="Puncak gunung di pagi hari" width="640" height="480">

Always include alt for images plus width and height so the browser doesn't jump while loading. A consistent order applies across the whole file and the whole project.

#Clear Class Naming

Class names describe a role, not an appearance. Avoid names like merah or kiri; choose names that survive design changes:

Role-based classes

<button class="tombol-primer">Simpan</button>
<button class="tombol-sekunder">Batal</button>

tombol-primer and tombol-sekunder stay meaningful even if their colors change. This pattern is similar to BEM and easy for any team to adopt.

#Comments and Automated Linting

#Comments That Explain Why

Use comments to explain the reasoning behind a decision, not to translate the code:

Helpful comments

<!-- Dibutuhkan untuk integrasi laporan lama -->
<div id="lap-r2" class="laporan" data-format="r2">
  Konten laporan.
</div>

Comments that merely repeat a tag are noise. Explain context invisible in the code, like an integration reason or a system constraint.

#Checking with html-validate

Linting tools catch problems that are easy to miss. Install and run html-validate from the terminal:

npm install --save-dev html-validate
npx html-validate "src/**/*.html"

The command npx html-validate "src/**/*.html" checks accessibility, misplaced elements, and duplicate attributes in one pass. Make linting part of your pre-commit workflow.

#Exercise: Tidying Up Markup

Clean up the following code block: replace div with semantic elements, fix the skipping headings, and make sure indentation is even:

Markup that needs tidying

<div>
  <h1>Pusat Bantuan</h1>
  <div>
    <h4>Mengatur ulang kata sandi</h4>
    <p>Klik tautan lupa kata sandi pada halaman masuk.</p>
  </div>
  <div>
    <h4>Memperbarui profil</h4>
    <p>Buka menu akun lalu pilih pengaturan.</p>
  </div>
</div>

The correct version uses section for each topic and h2 instead of h4. Compare your result with the examples from earlier episodes.

#Closing

Episode 19 builds your writing habits: consistent indentation, shallow nesting, semantic elements, a logical heading hierarchy, meaningful class naming, and automated linting.

Key takeaways:

• Consistent two-space indentation makes reading and reviewing changes easier.
• article, section, and aside convey meaning that div loses.
• One h1 per page and headings that don't skip.
• Class names describe roles, not appearances.
• Comments explain why, not what.
• html-validate catches problems before they reach production code.

In the next episode, episode 20, we'll cover responsive web with media queries and adaptive images — fluid layouts, sensible breakpoints, and srcset, sizes, and picture for sharp images on every screen.