8 Quick Tips On Organizing HTML Code

Welcome to a quick sharing of how to organize HTML code. Well, there are actually no hard rules on “we must organize HTML code in a certain way”. But just imagine taking over someone else’s code that is in a complete mess. The code may work, but it is full of syntax errors, has crazy camel case formatting all over, and it is totally illegible.

While we write code to render on computers, humans are still the ones to maintain it; It is equally important to write human-legible code. Just how do we properly organize HTML code? Here are a couple of things that I will always do – Read on!

 

 

TABLE OF CONTENTS

Download & Notes Organization Tips Useful Bits & Links
The End

 

DOWNLOAD & NOTES

Firstly, here is the download link to the example code as promised.

 

EXAMPLE CODE DOWNLOAD

Click here to download the source code, I have released it under the MIT license, so feel free to build on top of it or use it in your own project.

 

QUICK NOTES

If you spot a bug, please feel free to comment below. I try to answer questions too, but it is one person versus the entire world… If you need answers urgently, please check out my list of websites to get help with programming.

 

ORGANIZATION TIPS

All right, let us now move into the tips on how to better organize HTML code like a true code ninja.

 

1) PROPER HTML SKELETON STRUCTURE

1-proper-skeleton.html
<!DOCTYPE html>
<html>
  <head>
    <title>MY SITE</title>
    <meta name="description" content="DESCRIPTION HERE">
  </head>
  <body>
    CONTENTS
  </body>
</html>

This may be kind of a Captain Obvious thing, but my personal rule number 1 is to always start with a proper HTML page structure.

  • Make sure that the correct <!DOCTYPE> specification is right at the top. Yep… Don’t be surprised to see some beginners miss this out or do crazy things like <!doctype HTML5.0!>.
  • <html> to mark the start and end of the document.
  • The <head> section is optional as of HTML5, but always good to have, along with the <title> and <meta name="description">.
  • Finally, the <body> section itself.

Key point – Just keep a copy of this basic structure somewhere around.

 

 

2) USE SEMANTIC ELEMENTS

2-page-structure.html
<!DOCTYPE html>
<html>
  <body>
    <header>MY SITE</header>
 
    <nav>SITE NAVIGATION</nav>
 
    <main>
      <section>SECTION A</section>
      <section>SECTION B</section>
    </main>
 
    <footer>FOOTER</footer>
  </body>
</html>

Once upon a time in the dark ages of the Internet, the header, footer, body, sidebar, navigation bar, menu bar, breadcrumbs – We only used a single <div> tag to rule them all, and scattered comments like <!-- THIS PART IS THE HEADER / SIDEBAR / NAVIGATION / FOOTER --> all over to define which is which.

But ever since the introduction of HTML5, we have many new tags to deal with the page structures – <header> <main> <footer> <nav> <aside> <section>. Don’t be shy and adopt them, because one look and we will know which is which. Gone are the days of crazy comments, this will help both humans and search engines to better understand your website.

 

3) PROPER ORDER

3a-wrong-order.html
<!DOCTYPE html>
<html>
  <body>
    <!-- HEADER SECTION -->
    <main>
      <header>MY SITE</header>
      <nav>SITE NAVIGATION</nav>
    </main>
 
    <!-- BODY SECTION -->
    <main>
      <article>HELLO WORLD!</article>
      <footer>FOOTER</footer>
    </main>
 
    <!-- HIDDEN SIDE MENU -->
    <aside>
      <section>SECTION A</section>
      <section>SECTION B</section>
    </aside>
  </body>
</html>

Before you scroll down, the question is – What is wrong with the above page and layout?

3b-correct-order.html
<!DOCTYPE html>
<html>
  <body>
    <!-- HEADER SECTION -->
    <header>MY SITE</header>
    <nav>SITE NAVIGATION</nav>
 
    <!-- BODY SECTION -->
    <main>
      <!-- MAIN CONTENTS -->
      <article>HELLO WORLD!</article>
 
      <!-- HIDDEN SIDE MENU -->
      <aside>
        <section>SECTION A</section>
        <section>SECTION B</section>
      </aside>
    </main>
 
    <!-- FOOTER -->
    <footer>FOOTER</footer>
  </body>
</html>
  • There should only be 1 <main> tag on any given page.
  • Don’t wrap elements unless it is really necessary, keep the code clean. I.E. Avoid putting <header> <nav> <footer> <aside> into another container.
  • Try to create a “natural flow” that is easy to understand according to the design – <header> <nav> <main> <article> <aside> <footer>. I.E. Not a jumbled flow <main> <header> <nav> <main> <article> <footer> <aside>.

Yep. There are no hard rules as to which section have to come first or last, We can even put the <footer> at the top… But always ask yourself – Does it makes sense?

 

 

4) PROPER INDENTATION & NESTING

4-proper-indent.html
<!DOCTYPE html>
<html>
  <body>
    <!-- NO GOOD -->
    <ul>
    <li>First</li>
        <li>Second</li>
  <li>Third<ul>
          <li>Third-One</li>
      <li>Third-Two</li>
  </ul>
      </li>
<li>Forth</li>
          </ul>

    <!-- GOOD -->
    <ul>
      <li>First</li>
      <li>Second</li>
      <li>
        Third
        <ul>
          <li>Third-One</li>
          <li>Third-Two</li>
        </ul>
      </li>
      <li>Forth</li>
    </ul>
  </body>
</html>

I confess – It pisses me off when people don’t properly format and indent their code. Then, these very same people make a whole load of coding mistakes, and mumble something about “coding is very confusing, very difficult”.

How about start with doing proper indentation? Most code editors these days will do that automatically, even correct the wrong tags. You will be surprised how coding can “suddenly” become a lot “easier” when properly nested and indented.

 

5) BREAK LONG PROPERTY LISTS DOWN

5-long-property.html
<!DOCTYPE html>
<html>
  <body>
    <!-- NOPE -->
    <video class="stylevideo" id="myvideo" width="1920" height="1080" controls autoplay muted loop preload="metadata" src="http://mysite.com/assets/myvid.mp3" poster="http://mysite.com/assets/vidposter.jpg"></video>
 
    <!-- BETTER -->
    <video 
      class="stylevideo"
      id="myvideo"
      controls autoplay muted loop
      width="1920" height="1080" 
      preload="metadata" 
      src="http://mysite.com/assets/myvid.mp3"
      poster="http://mysite.com/assets/vidposter.jpg">
    </video>
  </body>
</html>

Some HTML elements can have a long… very long list of properties. Don’t just apply the “proper nesting” to the tags – Put it into use on the properties as well. It just makes things a lot easier to read (for humans).

 

 

6) COMMENT IF YOU MUST

6-do-comment.html
<!DOCTYPE html>
<html>
  <body>
    <form method="post" action="save-user.php">
      Email <input type="email" required/>
      Password <input type="password" required/>
      Confirm Password <input type="password" required/>

      <!-- @TODO - CONFIRM WITH CLIENT WHAT NEEDS TO BE CAPTURED -->
      Name ? Full Name <input type="text" required/>
      Birthday? Next-of-Kin? Tel?

      <input type="submit" value="Register"/>
    </form>
  </body>
</html>

I am not sure why some people on the Internet can give tips like “comments are useless and not required”. They are here for a good reason, and that is to put notes for yourself and others. Consider this – Let’s say that you are working on a user registration form for a client, but not sure what other information needs to be captured.

Rather than waiting for a reply, we can go ahead and create parts that are confirmed. A simple @TODO comment can help us in the future to turn back and complete this particular section. It is not just to mark out “to do” sections – Comments can also help to explain how certain sections work, and why it has to be so because of restrictions.

 

7) SIMPLE NAMING CONVENTION

7-id-class-name.html
<!-- NO GOOD -->
<img src="myphoto.jpg" class="UvUvWeVwEvWe-OnYeTeNyEvWe-UgWeMuBwEm-OsSaS"/>

<!-- GOOD -->
<img src="myphoto.jpg" class="img-res"/>

I have a confession to make again – It pisses me off when people go crazy with their “creative naming sense”. The id of a simple “first name” field can be called User-Form-Input-Entry-Field-First-Name. Yep… Why not just first-name or firstName? The shorter and easier to understand – Fewer mistakes will be made.

 

 

8) SEPARATE LONG SCRIPTS, OR NOT.

8a-long-script.js
var first = null;
var second = null;
var third = null;
var forth = null;
var fifth = null;
var sixth = "Just a random";
var seventh = "long long script";
var eighth = sixth + " " + seventh;
console.log("Hello World");
console.log("Foo Bar");
console.log(eighth);
8b-page.html
<!DOCTYPE html>
<html>
  <head>
    <script src="8a-long-script.js"></script>
  </head>
  <body>
    CONTENTS
  </body>
</html>

Have a long confusing script? Then separate it out as another .js file, load it as an external file instead… That is one way to remove the “visual clutter” and create a separation of concern. But also know that there will be some bad side effects – The more external scripts the page has, the slower the loading gets.

The browser has to request and fetch additional scripts from the server, and this is called the round-trip-time.

 

 

USEFUL BITS & LINKS

That’s all for this guide, and here is a small section on some extras and links that may be useful to you.

 

HUMAN LEGIBILITY VS PERFORMANCE

I can sense the angry toxic troll things banging on their keyboards. Oh, stupid tips. It is a complete waste of time structuring the code nicely. More spaces and indentations only add to the file size and loading bloat.

Well, that is only partially true. But consider the technologies that we have these days – We have fast Internet connections, we have powerful gaming smartphones. Also, there are many techniques these days such as GZIP and auto-minification. The extra comments and line breaks are not going to create a dent in the performance anyway.

As for “wasting time” to structure the code? Most good code editors do it automatically, just set it up once. It wastes more time trying to read messy code and trying to figure out what went wrong.

 

INFOGRAPHIC CHEAT SHEET

Tips For Organizing HTML Code (Click to enlarge)

 

LINKS & REFERENCES

 

THE END

Thank you for reading, and we have come to the end of this guide. I hope that it has helped you with your project, and if you want to share anything with this guide, please feel free to comment below. Good luck and happy coding!

Leave a Comment

Your email address will not be published. Required fields are marked *