Boas práticas de escrita de código HTML

Aprenda a escrever código limpo, indentado e legível — como arrumar a casa antes de receber visita.

Escrever código HTML não é apenas sobre fazer a página funcionar; é também sobre escrevê-lo de uma forma que seja limpa, organizada, legível e fácil de manter por você e por outras pessoas (ou pelo "você do futuro"). Pense nisso como arrumar a casa antes de receber visitas: um ambiente organizado é mais agradável e funcional para todos.

Adotar boas práticas desde o início vai te poupar muitas dores de cabeça e te tornar um desenvolvedor mais eficiente.

1. Indentação e Formatação Consistente

A indentação é o uso de espaços ou tabulações para criar uma hierarquia visual no seu código. Ela mostra claramente quais elementos estão aninhados dentro de outros.

  • O que fazer:

    • Use indentação consistente (ex: 2 ou 4 espaços, ou tabulações) para cada nível de aninhamento.
    • Mantenha um estilo de formatação consistente em todo o projeto. Ferramentas como Prettier ou o formatador embutido do seu editor de código podem ajudar muito.

  • Exemplo (bom):

    <body>
  <header>
    <nav>
      <ul>
        <li><a href="#">Início</a></li>
        <li><a href="#">Sobre</a></li>
      </ul>
    </nav>
  </header>
  <main>
    <section>
      <h1>Título da Seção</h1>
      <p>Conteúdo do parágrafo.</p>
    </section>
  </main>
</body>

  • Exemplo (ruim):

    <body>
<header>
<nav>
<ul>
<li><a href="#">Início</a></li>
<li><a href="#">Sobre</a></li>
</ul>
</nav>
</header>
<main>
<section>
<h1>Título da Seção</h1>
<p>Conteúdo do parágrafo.</p>
</section>
</main>
</body>

2. Uso de Minúsculas para Nomes de Tags e Atributos

O HTML não é case-sensitive para nomes de tags e atributos (ou seja, <DIV> funciona como <div>), mas a convenção e a boa prática é usar sempre minúsculas.

  • O que fazer:
    • Escreva todas as tags e atributos em minúsculas.
  • Exemplo (bom): <img src="imagem.jpg" alt="Descrição">
  • Exemplo (ruim): <IMG SRC="imagem.JPG" ALT="Descrição">

3. Fechamento de Tags

Embora alguns navegadores sejam tolerantes com tags não fechadas, é uma má prática e pode levar a comportamentos inesperados ou problemas de renderização.

  • O que fazer:
    • Sempre feche suas tags (ex: <div></div>, <p></p>).
    • Tags vazias (que não contêm conteúdo) não precisam de tag de fechamento, mas podem ser "auto-fechadas" (ex: <img />, <br />, <input />). No HTML5, o / final é opcional para tags vazias, mas é uma boa prática para consistência e compatibilidade com XML/XHTML.
  • Exemplo (bom): <p>Este é um parágrafo.</p>
  • Exemplo (ruim): <p>Este é um parágrafo.

4. Uso de Aspas para Valores de Atributos

Valores de atributos devem sempre estar entre aspas (simples ou duplas). Embora o HTML permita valores sem aspas em alguns casos, é uma má prática.

  • O que fazer:
    • Use aspas duplas (") ou simples (') para todos os valores de atributos.
    • Mantenha a consistência (ex: se começou com duplas, use duplas em todo o projeto).
  • Exemplo (bom): <a href="/sobre" class="link-menu">Sobre</a>
  • Exemplo (ruim): <a href=/sobre class=link-menu>Sobre</a>

5. Comentários no Código

Comentários são essenciais para explicar partes complexas do seu código, decisões de design ou seções que podem precisar de atenção futura.

  • O que fazer:

    • Adicione comentários para explicar a finalidade de blocos de código, seções complexas ou para deixar notas para você ou para outros desenvolvedores.

  • Exemplo:

    <!-- Seção de produtos em destaque -->
<section class="featured-products">
  <h2>Nossos Produtos</h2>
  <!-- TODO: Adicionar mais produtos aqui -->
</section>

6. HTML Semântico (Revisão e Reforço)

Já falamos sobre isso na acessibilidade, mas vale reforçar aqui como uma boa prática geral de escrita de código.

  • O que fazer:
    • Use as tags HTML que melhor descrevem o conteúdo que elas envolvem.
    • Pense no significado, não apenas na aparência.
  • Exemplo (bom): <nav><ul><li>...</li></ul></nav> para navegação.
  • Exemplo (ruim): <div class="menu"><ul><li>...</li></ul></div> (funciona, mas é menos semântico).

7. Estrutura de Documento HTML Completa

Sempre inclua a estrutura básica completa de um documento HTML.

  • O que fazer:

    • Comece com <!DOCTYPE html>.
    • Tenha a tag <html> com o atributo lang.
    • Tenha as tags <head> e <body>.
    • No <head>, inclua <meta charset="UTF-8"> e <meta name="viewport">.
    • Defina um <title> descritivo.

  • Exemplo:

    <!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Título da Minha Página</title>
</head>
<body>
  <!-- Conteúdo aqui -->
</body>
</html>

8. Evite Estilos e Scripts Inline (na maioria dos casos)

Misturar CSS e JavaScript diretamente no HTML torna o código mais difícil de ler, manter e reutilizar.

  • O que fazer:
    • Mantenha o CSS em arquivos .css externos (linkados no <head>).
    • Mantenha o JavaScript em arquivos .js externos (linkados no <head> com defer ou no final do <body>).
  • Exemplo (bom):
    <!-- HTML -->
<link rel="stylesheet" href="style.css">
<script src="script.js" defer></script>

    /* style.css */
.minha-div { color: blue; }

    // script.js
document.querySelector('.minha-div').addEventListener('click', () => { /* ... */ });
  • Exemplo (ruim):
    <div style="color: blue;" onclick="alert('Olá!');">Clique aqui</div>

Resumindo

Adotar essas boas práticas de escrita de código HTML desde o início vai te ajudar a criar projetos mais profissionais, fáceis de entender e de manter. Lembre-se que o código é lido muito mais vezes do que escrito, então invista na sua legibilidade!