Clean HTML

Published in

ArcTouch

8 min readMar 2, 2023

How To Write Clean HTML Code

Clean and well written code is essential for easy maintainability and clarity in software development. If you are developing with HTML, this will not be different, so you will need to be aware to write good markup code.

Here are four pillars of HTML code to to make pages easy to change, higher performance, more accessible, and search optimized. Let’s go :)

The four pillars of Clean HTML

This article explains the concepts of syntax, semantics, SEO, and accessibility, which are the 4 pillars of clean HTML. I include some examples that will define and explain each pillar.

Syntax

The book Clean Code shows some syntax rules that define good practices to write code, formatting, and organizing files. On the syntax pillar, we should consider the code formatting, and we will use especially the W3School Guide and the HTML5 actual patterns.

1. Use lowercase on all code

HTML is not case-sensitive. In other words, HTML does not verify if you write lowercase or uppercase on the elements, classes, or properties. Although it is possible to use, it’s not a good practice to write in different cases, because this will create messy code, and will not follow the current pattern used by a lot of developers, that’s the lowercase.

AVOID THIS
<BODY>
  <P> ArcTouch creates lovable apps and digital products. </p>
</BoDy>

DO THIS
<body>
  <p> ArcTouch creates lovable apps and digital products. </p>
</body>

2. Always close all the elements

Use close tags to organize and align the code indentation. Consider using self-closing elements, but in HTML5 they are optional.

AVOID THIS
<section>
  <p> Design & development services
</section>

DO THIS
<section>
  <p> Design & development services </p>
</section>

3. Do not forget quotes on attribute values

It’s possible to use a single quote or not use quotes, but usually developers use double quotes on attribute values. Double-quoted code is easier to read.

AVOID THIS
<section>
  <p class=services> apps </p>
  <p class='services'> websites </p>
  <p class=services"> digital products </p>
</section>

DO THIS
<section>
  <p class="services"> apps </p>
  <p class="services"> websites </p>
  <p class="services"> digital products </p>
</section>

4. Do not use spaces between equal signs

Avoiding spaces between equal signs will facilitate code reading.

AVOID THIS
<section>
  <p class = "contact"> Let's build something awesome. Together. </p>
</section>

DO THIS
<section>
  <p class="contact"> Let's build something awesome. Together. </p>
</section>

5. Use big comments in blocks

Breaking up large comments can make code difficult to read and maintain.

AVOID THIS
<!-- We help companies forge meaningful connections -->
<!-- with their customers through -->
<!-- lovable apps, websites, -->
<!-- and digital products. -->

DO THIS
<!-- We help companies forge meaningful connections
     with their customers through 
     lovable apps, websites,
     and digital products.
-->

6. Avoid unnecessary comments, or discontinued code commented

While the project is in development, the comments will be more of one part that you will need to work on, and do maintenance. So, removing some comments is important to avoid comments that describe some obvious information. Furthermore, it’s essential to remove some comments with discontinued code, because this will not be used more.

AVOID THIS
<!-- Bloco de main -->
<main></main>

<!-- <p> Paragrafo antigo </p> -->

7. Avoid except white lines

White lines are difficult the reading in extensive files. With a lot of white lines it will not be easy to verify all the indentation code levels.

AVOID THIS
<h1> any </h1>

<p>Confira 
</p>

DO THIS
<h1>any</h1>

<p>Confira</p>

8. Do not use CSS inline

CSS inline is a resource that can be used in some special cases, but it’s recommended to avoid because this could create a code less reusable. In some cases, if it is necessary to change some CSS, we could need to change more than one file, and this will generate extra work.

AVOID THIS
<p style="color:pink;"> any </p>

9. Remove optional elements

The newest HTML5 version includes some optional elements that could be removed, considering some special rules. For example, you could remove the tag <html> if the first thing inside the element is not a comment. For more details, review the other rules to omit optional tags.

AVOID THIS
<!DOCTYPE html>
<html>
  <head>
     <title> ArcTouch </class>
  </head>
  <body>
    <p> AN AKQA STUDIO </p>
  </body> 
</html>

DO THIS
<!DOCTYPE html>
<html>
  <title> ArcTouch </class>
  <p> AN AKQA STUDIO </p>
</html>

I’m not entirely convinced that this is a best practice, but it’s good to know that this is an option for you.

10. Adopt cohesion and syntax for names

Cohesion and syntax for strings is currently indicated in the Clean Code book. Do not exist exactly an irrefutable definition for the strings that define the names of classes, ids, and others. In this case, the indication is to define a partner for the project. Some patterns that you can analyze and use are the BEM pattern or Object-Oriented CSS pattern.

11. Indentation

It’s common that projects have different types and conventions for indentation and the pattern that we indicate here talked about orientations related to this topic. I believe that the most important practice is not to have hard rules, but to have consistency in the project patterns, use a standard for the entire project, and keep the code indented as it will facilitate visualization and understanding of the chaining of blocks.

SEMANTICS

The current HTML5 pattern describes semantic HTML as a meaning of the code for the browser. And, the main benefit of using semantic tags improves the best position on the SEO ranking and will guarantee the page accessibility to screen readers, having the best navigation.

SEO and accessibility will be explained in the next sections of this article.

Use the elements with their own purpose

Always use the elements with their own purpose. For example, the title element for titles and other elements in general. Here’s a guide:

header: identifies the header elements;
main: identifies the main content on the page;
footer: identifies the footer elements on the page;
nav: identifies links or menu sections;
section: identifies the content section;
figure: identifies an image;
aside: identifies the aside menu content;
article: could be a quote from external texts or references.
p: identifies a paragraph

2. Do not use deprecated tags

Some elements and attributes may be deprecated and may cause malfunctions on the page. It’s better to not use obsolete elements.

3. ARIA functions

The element definitions using the ARIA role attributes are used when semantic tags are not sufficient to specify the element function. With this attribute, tags that are not semantic may be.

<ul role="tablist">
   <li role="tab">Front-end</li>
   <li role="tab">Back-end</li>
</ul>

SEO

Search Engine Optimization (SEO) is the metrics and rules that validate and optimize the search ranking of the web pages and improve page authority.

SEO is directly associated with semantics and accessibility, so it’s possible to verify that some points in this section will be common in the other sections too. It’s important to understand that here we should talk just about HTML, but SEO needs a lot of definitions for success.

1. Aways use a title

Each section title will be like a main title. Ensure all titles are objective, and use keywords that indicate the page content and are unique.

2. Use headers in ascending order

Do not use excessive header tags. They may be difficult to understand the final and initial content for developers and screen readers. Using headers in ascending order also will improve the application accessibility.

AVOID THIS
<h2> Header 1 </h2>
<h1> Header 2 </h1>
<h3> Header 3 </h3>
<h5> Header 4 </h5>
<h4> Header 5 </h4>

DO THIS
<h1> Header 1 </h1>
<h2> Header 2 </h2>
<h3> Header 3 </h3>
<h4> Header 4 </h4>
<h5> Header 5 </h5>

3. Qualify external links

Qualifying the outbound links with the right attributes informs Google about the relationship between the actual page and the page to be opened.

There are 3 attributes available for this qualification:

sponsored: publicity links;
ugc: user-generated links;
nofollow: pages you can’t control the content.

<p> Vem conferir
  <a rel="sponsored"
     href="https://arctouch"> 
  </a>
</p>

4. Meta tags

Meta tags provide the page description to search engines. These also control how information about the page is shown on social networks.

<meta
     name="description"
     content="Site"
>

5. Define canonical URL

Sometimes content on a web page gets duplicated. There are lots of reasons why this happens and why it matters, such as the type of device, dynamic URLs, a lot of URLs, and other reasons. The canonical tag informs web browsers and search engines which is the correct page, and which are duplicates.

<link rel="canonical" href="https://arctouch" />

6. Set the publication date

The publication date is essential to all the searches on Google and help maintain data consistency. It’s not necessary to specify the hour, but if you do that, also provide the time zone.

<script type="application/ld+json"
      {
         "datePublished": "2021-07-20",
         "dateModified": "2021-07-20"
      }
</script>

ACCESSIBILITY

Some good practices are indicated in the Semantics and SEO sections, but there’s more to be done to ensure better accessibility.

1. Insert alternative text

Alternative text should describe images to help visually impaired people to understand all the context. Review these tips for writing good alternative text to describe content images.

<img alt=" ArcTouch logo in the colors of the pride flag" />

Add alternative text to all nondecorative images.
Keep it short and descriptive.
Do not include “image of” or “photography of.”
If the image is just decorative, without importance or meaning, do not write the alternative text.
For icons, include information about the function of the control. For example, if is a Save icon, the alternative text could be “save the file”.

2. Use good titles

Titles will guide people with disabilities that use the screen reader. Imagine that if you write a good title this person will verify all the titles and access just the exact section needed.

3. Declare the language in use

Usually, the screen reader will use the operating system language, but it’s possible that the website has internationalization implemented. In this case, the page may have a lot of associated languages. The lang attribute is used by the screen reader to translate the language for the correct one.

<html lang="en">
...
</html>

4. Do not use a table for page layout

Using tables to arrange elements on the page will limit page accessibility. Instead, use CSS and stylesheets.

These 4 pillars presented here are, in my opinion, the most important for the maintenance, good practices, and reusability of HTML code. Do you have any other recommendations? Please share with your colleagues.

Do you want to work on interesting website projects with worldclass clients? Visit the ArcTouch careers page and join us!