> For the complete documentation index, see [llms.txt](https://hyfbe.gitbook.io/teacher-curriculum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hyfbe.gitbook.io/teacher-curriculum/topics/notional-machines.md).

# Notional machines

what does it mean to learn a programming language and runtime environment?

One workable answer is [to learn a "notional machine"](https://teachtogether.tech/#s:models-notional).

Just a fancy way of saying that you are comfortable using words and diagrams to explain what is happening inside of the computer at any point in your program's execution. A series of

* visualizations
* diagrams
* refactoring techniques
* vocabulary

That are accurate but manageable; correct enough that you can use them to predict program state, debug your projects, and accurately translate between diagrams & code. But not so precise that you get lost in low-level implementation. An important feature of a notional machine is that they are not built on overly-familiar analogies. It should build new intuitions based on how teh programming language actually work, instead of building on old intuitions from elsewhere in life that sort-of work like the programming language.

An easy danger when teaching programming is relying too heavily on approachable analogies that are not quite correct. This is especially dangerous because programming languages & computers are not like other things students have learned before. An intuitions built off of previous experience can be misleading and can lead to un-learning later on.

Using a common set of visualization tools, and correct vocabulary from day 1 is super important. Building up a shared and correct understanding is only realistic when you, your peers and your coaches all discuss the same visuals with the same vocabulary.

## Topic Applied

A tricky part of teaching with notional machines is related to rule #6 from [teachtogether.tech](https://teachtogether.tech/#the-rules)

1. Never hesitate to sacrifice truth for clarity.

This is a fine line to walk. On one hand an approachable analogy is the definition of sacrificing truth for clarity. On the other hand, a misleading analogy will lead to less clarity in the future when a student learns something about their language that does not fit with the analogy they learned before.

## Topic Applied to JavaScript

Fortunately JavaScript has a couple tools that help you to teach a JS notional machine, and more importantly allow students to continue developing theirs while not in class:

* [JS Tutor](http://www.pythontutor.com/live.html#mode=edit) (everything synchronous and on the callstack)
* [Loupe](http://latentflip.com/loupe/?code=!!!) (the event loop)
* [Promisees](https://bevacqua.github.io/promisees) (promises)