Curso HTML 17.4 HTML legible: indentación, comentarios y organización

17.4 HTML legible: indentación, comentarios y organización

Es fundamental que el código HTML sea fácil de leer y mantener, tanto por ti como por otros desarrolladores. Una buena legibilidad se basa en tres pilares:

• Indentación coherente
• Comentarios claros
• Organización de archivos y secciones

1. Indentación coherente

La indentación muestra la estructura jerárquica del documento. Debe ser consistente en todas las páginas.

• Se suele usar 2 o 4 espacios por nivel, nunca tabulaciones mezcladas con espacios.
• Cada etiqueta hija debe indentarse respecto de su padre.
• Los elementos de lista, formularios o secciones anidadas ganan en claridad.

Ejemplo con 2 espacios de indentación:

<ul class='productos'>
  <li>
    <h2>Producto A</h2>
    <p>Descripción breve del producto A.</p>
    <ul>
      <li>Característica 1</li>
      <li>Característica 2</li>
    </ul>
  </li>
  <li>
    <h2>Producto B</h2>
    <p>Descripción breve del producto B.</p>
  </li>
</ul>

2. Comentarios claros

Los comentarios ayudan a entender fragmentos complejos o a marcar secciones importantes. Úsalos con moderación y escribe en un idioma coherente (por ejemplo, español).

• Comentarios de una línea para aclaraciones puntuales:

<!-- Inicio del formulario de registro de usuarios -->
<form action='/registro' method='post'>
  ...
</form>

• Comentarios multilínea para bloques más extensos:

<!--
  Sección de testimonios: 
  - Se repite con JavaScript
  - Cada testimonio incluye nombre, foto y comentario
-->
<section id='testimonios'>
  ...
</section>

• No abuses de los comentarios para “documentar” código obvio. Mejor refactoriza si algo es demasiado complejo.

3. Organización de archivos y secciones

Dividir tu proyecto en archivos y carpetas bien estructurados facilita su mantenimiento:

• index.html: Página principal.
• secciones/
  • header.html
  • footer.html
  • nav.html
• css/ para estilos
• js/ para scripts
• images/ para recursos gráficos

En el HTML principal, puedes incluir fragmentos con <!--#include virtual--> o usando tu gestor de plantillas:

<!-- index.html -->
<!DOCTYPE html>
<html lang='es'>
  <!-- Cabezal con meta y enlaces CSS -->
  <head>
    <title>Mi Sitio</title>
    <link rel='stylesheet' href='css/estilos.css'>
  </head>
  <body>
    <!-- Header común a todas las páginas -->
    <div class='header-wrapper'>
      <!--#include virtual='secciones/header.html' -->
    </div>

    <main>
      <h2>Bienvenido</h2>
      <p>Contenido principal de la página.</p>
    </main>

    <!-- Footer común a todas las páginas -->
    <div class='footer-wrapper'>
      <!--#include virtual='secciones/footer.html' -->
    </div>
  </body>
</html>

Buenas prácticas adicionales

• Usa nombres de clases y IDs descriptivos (BEM, SMACSS).
• Evita líneas de código demasiado largas; rompe atributos si exceden ~80 caracteres.
• Agrupa atributos en orden lógico (id, class, src/href, aria-*, data-*).
• Simplifica la estructura eliminando etiquetas innecesarias.

Siguiendo estas pautas conseguirás un código HTML más limpio, fácil de entender y de mantener en equipo.