Lesson Thursday

When you are writing HTML (or any other programming language), well-written code follows consistent indentation and spacing patterns. In some languages, indentation and spacing are even required for the code to function properly. While that's not the case with HTML or JavaScript, it's still very important to properly indent our code. Proper indentation makes our code cleaner and more readable. It also makes it easier to prevent bugs.

Indenting Code Two Spaces

There are two debates around indentation in the coding community. The first debate is on whether we should use spaces or tabs to indent our code. The second is on whether our indents should equal 2 spaces or 4 spaces.

During Intro to Programming, we indent our code 2 spaces and use tabs instead of spaces for indentation. The default tab size in VSCode is 4 spaces so we need to update it. We can set the tab size by going to Code > Preferences and then looking at the Commonly Used options. You'll see an Editor: Tab Size option which you can set to 2.

Type in 2 in Editor: Tab Size.

We'll discuss 2 versus 4 spaces and tabs versus spaces briefly at the end of the lesson.

Indenting HTML

Let's take a look at what good HTML indentation looks like - and then we'll look at an example of poor indentation.

<!DOCTYPE html>
<html lang="en-US">
<head>
  <title>Example title</title>
</head>
<body>
  <h1>Example header</h1>
  <h2>A smaller header</h2>

  <p>Page content</p>
</body>
</html>

As we see here, when an HTML tag is nested inside another HTML tag, it's indented. There is one exception: we didn't indent <head> and <body> inside of the <html lang="en-US"> tag even though <head> and <body> are nested inside it. This is common convention to save space. As our code gets more deeply nested, there can be a lot of empty space in our code editor and eventually our code will end up running off the screen. This is why we are proponents of 2 spaces of indentation instead of 4 - to save space in our code editor.

By the way, note that we can do the <html> tag on its own - however, we will always add lang (in our case lang="en-US"). This has two benefits: it provides better accessibility for screen readers for the visually impaired and it makes it easier for browser translation software to translate our HTML into other languages. We should make our sites more accessible if possible and this is an easy step we can make in that direction.

Now let's look at other examples of indentation in the HTML above. The <body> tag contains all of the HTML that a user sees on the page itself. Because all tags inside <body> are nested (such as <h1> and <h2>), they need to be indented two spaces more deeply than <body>.

However, note that the <h2> and <p> tags aren't indented past <h1>. This is because they aren't inside the <h1> closing tag (</h1>). We've found that some students are confused about this at first - and here's a common mistake we've seen from beginners:

<!-- This is not correct! Don't do this! -->
<h1>Here's a header.</h1>
  <h2>Here's a smaller header.</h2>
    <p>Here's some text.</p>

Organizationally, it kind of makes sense... but it's not correct.

An Aside About Comments...

By the way, you might be wondering about this syntax <!-- -->:

<!-- This is not correct! Don't do this! -->

This is called a comment. Most coding languages have the ability to add comments. Comments are messages for humans to read - the machine ignores them so they don't get run as code. In general, your code should speak for itself. That means you don't want to have too many comments. However, they can be very helpful. Note that the syntax for HTML comments <!-- --> is different than the syntax of comments in other languages. We won't worry about other languages yet, though!

Example of Poor Indentation

Let's get back to indentation. We've looked at an example of good indentation and one common mistake that beginners make. Now let's look at an example of bad indentation. See if you can fix it on your own. Then we'll go over what's wrong and how to fix it.

<!DOCTYPE html>
<html lang="en-US">
    <head>
    <title>Example title</title>
    </head>
  <body>
    <h1>Example header</h1>
      <h2>A smaller header</h2>
        <p>Page content</p>
  </body>
</html>

Now let's take a closer look line by line at the issues:

  • <head> is indented 4 spaces. The important thing here is we need to be consistent. While both 2 and 4 spaces are acceptable for indentation, you can't mix and match them. Because we are using 2 spaces for indentation, <head> should only be indented 2 spaces. This also affects the closing tag </head>, which should only be indented 2 spaces as well.
  • Currently, <title> is not indented further than <head> even though it's nested inside <head>. It needs to be indented 2 more spaces than <head>. We don't actually have to change its position, though, because it will be indented correctly once the issue with the <head> tag is fixed.
  • <h2> is nested more deeply than <h1> even though it isn't inside the <h1> closing tag. <h2> should be at the same level as <h1> - and for that matter, so should the <p> tag.

Tabs Versus Spaces... 2 Spaces Versus 4

Now that we've covered the basics of indentation, let's briefly get into the debate about tabs versus spaces and 2 spaces versus 4 when it comes to indentation. All of these choices are valid - though the TV show Silicon Valley (a satire about computer programmers) turned spaces versus tabs into both a joke and a heated debate. So let's look at the pros and cons of both - and why Epicodus does things one way and not the other.

Tabs Versus Spaces

The argument in favor of tabs is that it takes fewer keystrokes. A single tab will be consistent while you may accidentally press the space bar one too many - or one too few times - resulting in indentation issues. This is especially problematic for beginners, where it can be difficult to line up spaces correctly. That's why we recommend using tabs.

The argument against tabs is that different machines are configured differently. One developer's tab might be two spaces while another's might be four spaces. So a tab might mean one thing to one coder and a different thing to another. Meanwhile, a space is always a space.

2 Spaces Versus 4

The argument in favor of 2 spaces is that it takes up less space in your code editor - which can be especially useful on a laptop's smaller screen. There is more room for your code - and you'll be staring at less blank space. When a file has many levels of nesting (as you might see in a longer HTML document), your code won't run off the screen as much.

We know a lot of our students have smaller screens - and deeply nested code is often unavoidable in HTML documents. That's why we prefer 2 spaces.

The argument for 4 spaces is that code is more readable. The folks at Microsoft - and many C#/.NET developers - argue for 4 spaces. That is why VS Code has a default of 4 spaces. They argue that deeply nested code is a sign of badly-written code - so it shouldn't be going off your screen much anyway.

Ultimately, neither of these options are wrong. The most important thing is to be consistent everywhere in your code!

Regardless of the language you use to write code, learn the indentation and spacing standards for it. Practice consistency so that your code is easily readable to other developers as well as your future self.

For now, even with 2 space indentation, you will often find content in your code going off the screen. This can be very annoying. Fortunately, there's a setting in VS Code to ensure all your code is showing. Go to View > Toggle Word Wrap. This forces the text in your screen to wrap inside the screen of your code editor. You can easily toggle it on or off. Occasionally, wrapping text can make it more difficult to see how code is indented - but it's generally a great tool for making sure you can see all of your code.

Summary


  • In HTML, the beginning and ending tags of an element on multiple lines should always be left-aligned. For example, when you see <html lang="en-US">, you should be able to visually scan the page straight down to find its closing tag (the same for <head> and <body>). One way to implement this is to create opening and closing tags at the same time and then add the contents.

Lesson 16 of 22
Last updated June 22, 2020