Add a note about avoiding function hoisting #75

After discussions in dev meeting we decided to avoid hoisting to avoid confusion and PR back-and-forth. We tried adding a lint rule but it was overly aggressive so I'm adding a note here instead.

Note: I removed/replaced some old content about the difference between function declarations and function expressions since it seems less relevant if we're avoiding hoisting. I'm happy to put it back in if others feel differently.

Author: Paul-Hebert

javascript/README.md

@@ -759,44 +759,71 @@ function sayHi(name) {
 
 ## Functions
 
-### 6.1 Function Style
+### 6.1 Avoid Function Hoisting
 
-Understand the difference between **function declarations** and **function expressions**.
+Although it is possible to call functions before they are defined via [hoisting](https://developer.mozilla.org/en-US/docs/Glossary/Hoisting) we prefer to avoid this pattern in our code as it can be confusing.
 
-> The primary difference between function declarations and function expressions is that declarations are hoisted to the top of the scope in which they are defined, which allows you to write code that uses the function before its declaration.
+#### Examples
 
-It can be argued that using function expressions will result in more a structured code base. We do not have a strict rule of using function declarations vs function expressions but wanted to document the difference between the two.
+Although this code works properly it may be more confusing and we generally avoid it:
 
-#### Examples
+```js
+logFoo();
+
+function logFoo() {
+  console.log("foo");
+}
+```
+
+We would prefer one of the following patterns:
+
+```js
+// Define the function before calling
+function logFoo() {
+  console.log("foo");
+}
+
+logFoo();
+```
+
+```js
+// Import the function
+import {logFoo} from './log-foo.js';
 
-> Function declarations in JavaScript are hoisted to the top of the enclosing function or global scope. You can use the function before you declared it:
->
-> ```js
-> hoisted(); // logs "foo"
->
-> function hoisted() {
->   console.log('foo');
-> }
-> ```
-
-> Although this code might seem like an error, it actually works fine because JavaScript engines hoist the function declarations to the top of the scope. That means this code is treated as if the declaration came before the invocation.
-
-> Note that function expressions are not hoisted:
->
-> ```js
-> notHoisted(); // TypeError: notHoisted is not a function
-> 
-> var notHoisted = function() {
->    console.log('bar');
-> };
-> ```
-
-
-### Resources
-
-- MDN Web Docs
-  - [Function Declaration]
-  - [Function Expression]
+logFoo();
+```
+
+In files that call a number of helper functions it can be helpful to move those functions to modules, or start the file with a main function that provides a summary of the steps taken in the file. For example:
+
+```js
+// The `main` function contains an overview of the file's logic.
+// (`main` could be switched to a more meaningful name in context.)
+function main() {
+  thing1();
+  thing2();
+  thing3();
+  thing4();
+}
+
+function thing1() {}
+function thing2() {}
+function thing3() {}
+function thing4() {}
+
+main();
+```
+
+Another option is to move helper functions to modules:
+
+```js
+// Import helpers so they're defined up front
+import {thing1, thing2, thing3, thing4} from './helpers.js';
+
+thing1();
+thing2();
+thing3();
+thing4();
+```
 
 ### 6.2 Function Arguments Parameter