8 Quick & Easy 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!

 

 

TLDR – QUICK SLIDES

[web_stories_embed url=”https://code-boxx.com/web-stories/quick-tips-to-organize-html-code/” title=”Quick Tips To Organize HTML Code” poster=”https://code-boxx.com/wp-content/uploads/2022/03/STORY-HTML-20230505.webp” width=”360″ height=”600″ align=”center”]

Fullscreen Mode – Click Here

 

TABLE OF CONTENTS

 

DOWNLOAD & NOTES

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

 

QUICK NOTES

If you spot a bug, feel free to comment below. I try to answer short 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.

 

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.

 

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 your “empty HTML page” somewhere.

 

 

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, we used a single <div> tag to rule them – The header, footer, body, sidebar, navigation bar, menu bar, breadcrumbs. The only way to distinguish them is to scatter comments like <!-- START : HEADER --> and <!-- END : HEADER --> all over the place.

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 has to come first or last, We can even put the <footer> at the top… But always ask yourself – Does it make any 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 starting with some proper indentation? Most code editors these days will do that automatically, they 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 leave 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 done 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, the fewer mistakes will be made.

 

 

8) SEPARATE LONG SCRIPTS

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”, but take note of the “side effect” – The more external scripts a page has, the slower the loading gets. This happens because the browser has to request and fetch additional scripts from the server.

 

 

EXTRA 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 to structure 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 smartphones. Also, there are many techniques these days such as GZIP, buffering, preloading, and auto-minification. The extra comments and line breaks are not going to make a dent in the performance.

As for “wasting time” to structure the code? Most good code editors already do it automatically, out of the box. Which is a greater waste of time? Trying to figure out messy code or running “auto-indent” in the editor within a few seconds?

 

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!

1 thought on “8 Quick & Easy Tips On Organizing HTML Code”

  1. just been looking and using your Tips on Organizing
    I love what you said about indentation and the
    trolls who post rubbish.Keep up the excellent work
    I enjoy your posts.Very informative,Easy to read and download,
    Keep up the good work. you get 100/10 from me.
    best Regards..

Leave a Comment

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