Integrate editing for Chapter 10

Author: marijnh

10_modules.md

@@ -14,8 +14,8 @@ quote}}
 
 {{index organization, "code structure"}}
 
-The ideal program has a crystal clear structure. It's easy to explain
-how it works, and each part plays a well-defined role.
+The ideal program has a crystal clear structure. The way it works is
+easy to explain, and each part plays a well-defined role.
 
 {{index "organic growth"}}
 
@@ -47,22 +47,22 @@ dirty.
 
 _Modules_ are an attempt to avoid these problems. A ((module)) is a
 piece of program that specifies which other pieces it relies on (its
-_dependencies_), and which functionality it provides for other modules
+_dependencies_) and which functionality it provides for other modules
 to use (its _((interface))_).
 
 {{index "big ball of mud"}}
 
 Module interfaces have a lot in common with object interfaces, as we
 saw them in [Chapter ?](object#interface). They make part of the
-module available to the outside world, and keep the rest private. By
+module available to the outside world and keep the rest private. By
 restricting the ways in which modules interact with each other, the
-system becomes more like ((Lego)), where pieces interact through
+system becomes more like ((LEGO)), where pieces interact through
 well-defined connectors, and less like mud, where everything mixes
 with everything.
 
 {{index dependency}}
 
-The relations between modules are called dependencies. When a module
+The relations between modules are called _dependencies_. When a module
 needs a piece from another module, it is said to depend on that
 module. When this fact is clearly specified in the module itself, it
 can be used to figure out which other modules need to be present to be
@@ -97,9 +97,9 @@ might be able to apply the same piece in different programs.
 
 But how do you set this up? Say I want to use the `parseINI` function
 from [Chapter ?](regexp#ini) in another program. If it is clear what
-it depends on (in this case, nothing), I can just copy all the
-necessary code into my new project, and use it. But then, if I find a
-mistake in that code, I'll probably fix it in whichever program that
+the function depends on (in this case, nothing), I can just copy all the
+necessary code into my new project and use it. But then, if I find a
+mistake in that code, I'll probably fix it in whichever program 
 I'm working with at the time and forget to also fix it in the other
 program.
 
@@ -141,8 +141,10 @@ can be found on there. For example, an INI file parser, similar to the
 one we built in [Chapter ?](regexp), is available under the package
 name `ini`.
 
+{{index "command line"}}
+
 [Chapter ?](node) will show how to install such packages locally using
-the `npm` ((command line)) program.
+the `npm` command-line program.
 
 Having quality packages available for download is extremely valuable.
 It means that we can often avoid reinventing a program that a hundred
@@ -207,9 +209,9 @@ console.log(weekDay.name(weekDay.number("Sunday")));
 
 This style of modules provides ((isolation)), to a certain degree, but
 it does not declare dependencies. Instead, it just puts its
-((interface)) into the ((global scope)), and expects its dependencies,
+((interface)) into the ((global scope)) and expects its dependencies,
 if any, to do the same. For a long time this was the main approach
-used in web programming, but is mostly obsolete now.
+used in web programming, but it is mostly obsolete now.
 
 If we want to make dependency relations part of the code, we'll have
 to take control of loading dependencies. Doing that requires being
@@ -257,7 +259,7 @@ console.log(plusOne(4));
 ```
 
 This is precisely what we need for a module system. We can wrap the
-module's code in a function, and use that function's scope as module
+module's code in a function and use that function's scope as module
 ((scope)).
 
 ## CommonJS
@@ -279,7 +281,7 @@ the module is loaded and returns its ((interface)).
 {{index "exports object"}}
 
 Because the loader wraps the module code in a function, modules
-automatically get their own local scope. The only thing they have to
+automatically get their own local scope. All they have to
 do is call `require` to access their dependencies, and put their
 interface in the object bound to `exports`.
 
@@ -310,7 +312,7 @@ exports.formatDate = function(date, format) {
     if (tag == "dddd") return days[date.getDay()];
   });
 };
-````
+```
 
 {{index "destructuring binding"}}
 
@@ -381,10 +383,10 @@ available in the module's ((scope)).
 
 {{index resolution, "relative path"}}
 
-The way the string given to `require` is translated to an actual file
-name or web address differs in different systems. When it starts with
+The way the string given to `require` is translated to an actual
+filename or web address differs in different systems. When it starts with
 `"./"` or `"../"`, it is generally interpreted as relative to the
-current module's file name. So `"./format-date"` would be the file
+current module's filename. So `"./format-date"` would be the file
 named `format-date.js` in the same directory.
 
 When the name isn't relative, Node.js will look for an installed
@@ -408,7 +410,7 @@ console.log(parse("x = 10\ny = 20"));
 
 ## ECMAScript modules
 
-((CommonJS modules)) work quite well, and in combination with NPM they
+((CommonJS modules)) work quite well and, in combination with NPM, 
 have allowed the JavaScript community to start sharing code on a large
 scale.
 
@@ -446,7 +448,7 @@ appear in front of a function, class, or binding definition (`let`,
 `const`, or `var`).
 
 An ES module's interface is not a single value, but a set of named
-((binding))s. The above module binds `formatDate` to a function. When
+((binding))s. The preceding module binds `formatDate` to a function. When
 you import from another module, you import the _binding_, not the
 value, which means an exporting module may change the value of the
 binding at any time, and the modules that import it will see its new
@@ -477,13 +479,13 @@ console.log(dayNames.length);
 ```
 
 At the time of writing, the JavaScript community is in the process of
-adopting this module style. But this has been a slow process. It took
+adopting this module style. But it has been a slow process. It took
 a few years, after the format was specified, for browsers and Node.js
 to start supporting it. And though they mostly support it now, this
 support still has issues, and the discussion on how such modules
 should be distributed through ((NPM)) is still ongoing.
 
-Many projects are written using ES modules, and then automatically
+Many projects are written using ES modules and then automatically
 converted to some other format when published. We are in a
 transitional period in which two different module systems are used
 side-by-side, and it is useful to be able to read and write code in
@@ -502,14 +504,14 @@ JavaScript.
 
 To make this possible, they _compile_ their code, translating it from
 their chosen JavaScript dialect to plain old JavaScript—or even to a
-past version of JavaScript so that old ((browsers)) can run it.
+past version of JavaScript—so that old ((browsers)) can run it.
 
 {{index latency, performance}}
 
-Including a modular program that consists of two hundred different
+Including a modular program that consists of 200 different
 files in a ((web page)) produces its own problems. If fetching a
 single ((file)) over the ((network)) takes 50 milliseconds, loading
-the whole program takes ten seconds, or maybe half that if you can
+the whole program takes 10 seconds, or maybe half that if you can
 load several files simultaneously. That's a lot of wasted time.
 Because fetching a single big file tends to be faster than fetching a
 lot of tiny ones, web programmers have started using tools that roll
@@ -544,7 +546,7 @@ Structuring programs is one of the subtler aspects of programming. Any
 nontrivial piece of functionality can be modeled in various ways.
 
 Good program design is subjective—there are trade-offs involved, and
-matters of taste. The best way to learn the value of well structured
+matters of taste. The best way to learn the value of well-structured
 design is to read or work on a lot of programs and notice what works
 and what doesn't. Don't assume that a painful mess is "just the way it
 is". You can improve the structure of almost everything by putting
@@ -569,7 +571,7 @@ you're likely to remember how to use it.
 
 Even if there's no standard function or widely used package to
 imitate, you can keep your modules predictable by using simple ((data
-structure))s and doing a single, focused thing. Many of the INI file
+structure))s and doing a single, focused thing. Many of the INI-file
 parsing modules on NPM provide a function that directly reads such a
 file from the hard disk and parses it, for example. This makes it
 impossible to use such modules in the browser, where we don't have
@@ -579,7 +581,7 @@ function.
 
 {{index "pure function"}}
 
-Which points at another helpful aspect of module design—the ease with
+Which points to another helpful aspect of module design—the ease with
 which something can be composed with other code. Focused modules that
 compute values are applicable in a wider range of programs than bigger
 modules that perform complicated actions with side effects. An INI
@@ -611,8 +613,8 @@ An example of a slightly more complex data structure is the graph from
 properties hold arrays of strings—the other nodes reachable from that
 node.
 
-There are several different path-finding packages on ((NPM)), but none
-of them use this graph format. They usually allow the graph's edges to
+There are several different pathfinding packages on ((NPM)), but none
+of them uses this graph format. They usually allow the graph's edges to
 have a weight, the cost or distance associated with it, which isn't
 possible in our representation.
 
@@ -645,9 +647,9 @@ console.log(find_path(graph, "Post Office", "Cabin"));
 ```
 
 This can be a barrier to composition—when various packages are using
-different data structures to describe similar things, it is difficult
-to combine them. Therefore, if you want to design for composability,
-find out what ((data structure))s other people are using, and when
+different data structures to describe similar things, combining them
+is difficult. Therefore, if you want to design for composability,
+find out what ((data structure))s other people are using and, when
 possible, follow their example.
 
 ## Summary
@@ -658,7 +660,7 @@ the part of the module that's visible from other modules, and the
 dependencies are the other modules that it makes use of.
 
 Because JavaScript historically did not provide a module system, the
-CommonJS system was built on top of it. But at some point it _did_ get
+CommonJS system was built on top of it. Then at some point it _did_ get
 a built-in system, which now coexists uneasily with the CommonJS
 system.
 
@@ -696,7 +698,7 @@ would you create? Which module would depend on which other module, and
 what would their interfaces look like?
 
 Which pieces are likely to be available pre-written on NPM? Would you
-prefer to use an NPM package or to write them yourself?
+prefer to use an NPM package or write them yourself?
 
 {{hint
 
@@ -708,7 +710,7 @@ way to design a given module):
 {{index "dijkstrajs package"}}
 
 The code used to build the road graph lives in the `graph` module.
-Because I'd rather use `dijkstrajs` from NPM than our own path-finding
+Because I'd rather use `dijkstrajs` from NPM than our own pathfinding
 code, we'll make this build the kind of graph data that `dijkstajs`
 expects. This module exports a single function, `buildGraph`. I'd have
 `buildGraph` accept an array of two-element arrays, rather than
@@ -726,7 +728,7 @@ the `./roads` module, because it needs to be able to verify that a
 given road exists. It also needs `randomPick`. Since that is a
 three-line function, we could just put it into the `state` module as
 an internal helper function. But `randomRobot` needs it too. So we'd
-have to either duplicate it, or put it into its own module. Since this
+have to either duplicate it or put it into its own module. Since this
 function happens to exist on NPM in the `random-item` package, a good
 solution is to just make both modules depend on that. We can add the
 `runRobot` function to this module as well, since it's small and
@@ -745,7 +747,7 @@ be read on its own. Dividing code into modules also often suggests
 further improvements to the program's design. In this case, it seems a
 little odd that the `VillageState` and the robots depend on a specific
 road graph. It might be a better idea to make the graph an argument to
-the state's constructor and to make the robots read it from the state
+the state's constructor and make the robots read it from the state
 object—this reduces dependencies (which is always good) and makes it
 possible to run simulations on different maps (which is even better).
 
@@ -758,7 +760,7 @@ does tend to clutter your modules.
 
 However, you should also not underestimate the work involved in
 _finding_ an appropriate NPM package. And even if you find one, it
-might not work well, or be missing some feature that you need. On top
+might not work well or may be missing some feature you need. On top
 of that, depending on NPM packages means you have to make sure they
 are installed, you have to distribute them with your program, and you
 might have to periodically upgrade them.
@@ -773,7 +775,7 @@ hint}}
 {{index "roads module (exercise)"}}
 
 Write a ((CommonJS module)), based on the example from [Chapter
-?](robot), which contains the array of roads and exports the graph
+?](robot), that contains the array of roads and exports the graph
 data structure representing them as `roadGraph`. It should depend on a
 module `./graph`, which exports a function `buildGraph` that is used
 to build the graph. This function expects an array of two-element
@@ -829,8 +831,8 @@ don't access each other's interface until after they finish loading,
 cyclic dependencies are okay.
 
 The `require` function given [earlier in this
-chapter](modules#require) supports this type of dependency cycles. Can
-you see how it handles them? What would go wrong when a module in a
+chapter](modules#require) supports this type of dependency cycle. Can
+you see how it handles cycles? What would go wrong when a module in a
 cycle _does_ replace its default `exports` object?
 
 {{hint

20_node.md

@@ -1051,11 +1051,11 @@ callback functions, and Node will call them with an error value and
 
 {{index grep, search, "search tool (exercise)"}}
 
-On ((Unix)) systems, there is a command line tool called `grep` that
+On ((Unix)) systems, there is a command-line tool called `grep` that
 can be used to quickly search files for a ((regular expression)).
 
 Write a Node script that can be run from the ((command line)) and acts
-somewhat like `grep`. It treats its first command line argument as a
+somewhat like `grep`. It treats its first command-line argument as a
 regular expression, and any further arguments as files to search. It
 should output the names of any file whose content matches the regular
 expression.
@@ -1075,7 +1075,7 @@ amount, since most file systems can only read one thing at a time.
 
 {{index "RegExp class", "search tool (exercise)"}}
 
-Your first command line argument, the ((regular expression)), can be
+Your first command-line argument, the ((regular expression)), can be
 found in `process.argv[2]`. The input files come after that. You can
 use the `RegExp` constructor to go from a string to a regular
 expression object.
@@ -1101,7 +1101,7 @@ capitalization—Node's file system function naming is loosely based on
 standard Unix functions, such as `readdir`, which are all lowercase,
 but then it adds `Sync` with a capital letter).
 
-To go from a file name read with `readdir` to a full path name, you
+To go from a filename read with `readdir` to a full path name, you
 have to combine it with the name of the directory, putting a ((slash
 character)) (`/`) between them.