Verbalizing code

A quick primer on reading code & learning to speak code—helps with cognition and memory.

Watch the video playlist

  1. Video or tutorial

    You can watch the video(s) or follow along with the written tutorial—or both—they convey exactly the same information.

1 Code is words

First & foremost, the code we write is for human beings. It’s for humans to consume. It’s for humans to updates. And it’s for humans to understand.

We need to be able to read the code to better understand what it’s try to accomplish.

Learning to read our code correctly can help our brains understand how to apply the code—and especially help us remember the code.

2 Glossary

When it comes to HTML, here are a few keywords you should remember when speaking out your code.

  • Tag — the primary driver of HTML’s code syntax, a word starting with < and ending with >, e.g. <h1>, <ul>, <article>
  • Open tag — the part that begins HTML content, starts with <, has one or more words, and ends with >, e.g. <p>, <div>, <time>
  • Close tag — the part that finalizes the chunk of HTML content, starting with </, then 1 word, then >, e.g. </p>, </div>, </time>
  • Attribute — extra, meta information, stored inside the open tag—never in the close tag, e.g. class="", src=""
  • Element — is a shortform way to say the open tag, its attributes, all the content inside, and the close tag. Some elments only have an open tag, like <img>
  • Document — the whole contents of the HTML file, all the code, all the content.
  • Head — the meta information stored within the open & close <head> tags.
  • Body — the HTML document’s content, stored between the open & close <body> tags.

3 Pronouncing tags

When pronouncing a tag, read its name and whether it’s an open or close tag:

  • <h1> — “Open H.1. tag”
  • </h1> — “Close H.1. tag”

Sometimes it makes sense to expand the tag’s name when reading it:

  • <img> — “Image tag”
  • <abbr> — “Abbreviation tag”

But I probably wouldn’t expand some tags:

  • <div> — I’d say, “Div. tag” instead of “Division tag”
  • <ol> — I’d say, “O.L. tag” instead of “Ordered list tag”

Though, when learning, it would be very helpful to read the full tag to help remember.

4 Pronouncing attributes

When pronouncing attributes, all you have to say is the attribute name, and maybe “equals”—it’s not really helpful to speak the quotation marks.

  • class="big" — “Class equals big”
  • datetime="2058-10-28" — “Date time equals 2058 dash 10 dash 28”

Sometimes, like HTML tags, it’s helpful to speak the full word:

  • src="/images/dino.svg" — “Source equals slash images slash dino dot S.V.G”

Usually you’d announce the attribute immediately after the open tag:

  • <img src="/images/dino.svg" — “Image tag, source attribute equals slash images slash dino dot S.V.G”

5 Example reading HTML content

Have a listen & watch of me reading out a chunk of HTML code. Then below you can do some practice.

6 Practice chunks

Here are a couple blocks of code for you to practice reading. They have companion spoken versions for you to hear.

<h2>Comments</h2>
<ol>
  <li>
    <article>
      <h3>Stegosaurus</h3>
      <time datetime="2054-04-04">April, 4, 2054</time>
      <p>These humans are so weird—they were so boring looking without back plates or feathers.</p>
    </article>
  </li>
</ol>

Here’s another block of code to practic reading.

<nav>
  <ul class="nav">
    <li>
      <a href="/dinosaurs">Dinosaurs</a>
      <ul class="sub-nav">
        <li><a href="/dinosaurs/plant-eaters">Plant-eaters</a></li>
        <li><a href="/dinosaurs/meat-eaters">Meat-eaters</a></li>
        <li><a href="/dinosaurs/omnivores">Omnivores</a></li>
      </ul>
    </li>
    <li>
      <a href="/pterasaurs">Pterasaurs</a>
    </li>
    <li>
      <a href="/plesiosaurs">Plesiosaurs</a>
    </li>
  </ul>
</nav>

Keep practicing reading and speaking code. You’re going to have to record yourself reading code for assignments in the future.

  1. comment.html — Line A

    Listen to this piece of code being read out.

  2. navigation.html — Line A

    Listen to this piece of code being read out.