docs(style-guide): copy edits applying guidelines (#3403)

Author: kapunahelewong

public/docs/ts/latest/guide/style-guide.jade

@@ -1,15 +1,29 @@
 include ../_util-fns
 
 :marked
-  Welcome to the Angular Style Guide
-
-  ## Purpose
-
   Looking for an opinionated guide to Angular syntax, conventions, and application structure?
   Step right in!
-  This style guide presents our preferred conventions and, as importantly, explains why.
+  This style guide presents preferred conventions and, as importantly, explains why.
+
 .l-main-section
+a(id='toc')
 
+:marked
+  # Contents
+
+    * [Single responsibility](#single-responsibility)
+    * [Naming](#naming)
+    * [Coding conventions](#coding-conventions)
+    * [App structure and Angular modules](#application-structure-and-angular-modules)
+    * [Components](#components)
+    * [Directives](#directives)
+    * [Services](#services)
+    * [Data services](#data-services)
+    * [Lifecycle hooks](#lifecycle-hooks)
+    * [Appendix](#appendix)
+
+
+.l-main-section
 :marked
   ## Style vocabulary
 
@@ -32,6 +46,11 @@ include ../_util-fns
 .s-rule.avoid
   :marked
     **Avoid** indicates something you should almost never do. Code examples to *avoid* have an unmistakeable red header.
+
+.s-why
+  :marked
+    **Why?** gives reasons for following the previous recommendations.
+
 .l-main-section
 
 :marked
@@ -40,37 +59,20 @@ include ../_util-fns
   Some code examples display a file that has one or more similarly named companion files. 
   For example, `hero.component.ts` and `hero.component.html`.
 
-  The guideline will use the shortcut `hero.component.ts|html|css|spec` to represent those various files. Using this shortcut makes this guide's file structures easier to read and more terse.
-
-.l-main-section
-a(id='toc')
-
-:marked
-  ## Table of contents
-
-    1. [Single responsibility](#single-responsibility)
-    1. [Naming](#naming)
-    1. [Coding conventions](#coding-conventions)
-    1. [App structure and Angular modules](#application-structure-and-angular-modules)
-    1. [Components](#components)
-    1. [Directives](#directives)
-    1. [Services](#services)
-    1. [Data services](#data-services)
-    1. [Lifecycle hooks](#lifecycle-hooks)
-    1. [Appendix](#appendix)
+  The guideline uses the shortcut `hero.component.ts|html|css|spec` to represent those various files. Using this shortcut makes this guide's file structures easier to read and more terse.
 
 .l-main-section
+a#single-responsibility
 :marked
   ## Single responsibility
 
   Apply the 
-  <a href="https://wikipedia.org/wiki/Single_responsibility_principle" target="_blank"><i>Single Responsibility Principle</i> (SRP)</a>
+  <a href="https://wikipedia.org/wiki/Single_responsibility_principle" target="_blank"><i>single responsibility principle</i> (SRP)</a>
   to all components, services, and other symbols. 
   This helps make the app cleaner, easier to read and maintain, and more testable.
 
-a#rule-of-one
-:marked
-  ### <a id="01-01"></a>_Rule of One_
+
+  ### <a id="01-01"></a>Rule of One
   #### <a href="#01-01">Style 01-01</a>
 .s-rule.do
   :marked
@@ -95,7 +97,9 @@ a#rule-of-one
 :marked
   The key is to make the code more reusable, easier to read, and less mistake prone.
 
-  The following *negative* example defines the `AppComponent`, bootstraps the app, defines the `Hero` model object, and loads heroes from the server ... all in the same file. *Don't do this*.
+  The following *negative* example defines the `AppComponent`, bootstraps the app, 
+  defines the `Hero` model object, and loads heroes from the server all in the same file. 
+  *Don't do this*.
 
 +makeExample('style-guide/ts/src/01-01/app/heroes/hero.component.avoid.ts', '', 'app/heroes/hero.component.ts')(avoid=1)
 :marked
@@ -349,12 +353,12 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** suffix a service class name with Service. 
+    **Do** suffix a service class name with `Service`. 
     For example, something that gets data or heroes 
     should be called a `DataService` or a `HeroService`.
 
     A few terms are unambiguously services. They typically 
-    indicate agency by ending in "er". You may prefer to name 
+    indicate agency by ending in "-er". You may prefer to name 
     a service that logs messages `Logger` rather than `LoggerService`. 
     Decide if this exception is agreeable in your project. 
     As always, strive for consistency.
@@ -421,7 +425,7 @@ a(href="#toc") Back to top
 
 .s-rule.avoid
   :marked
-    **Avoid** putting app logic in the `main.ts`. Instead, consider placing it in a component or service.
+    **Avoid** putting app logic in `main.ts`. Instead, consider placing it in a component or service.
 
 .s-why
   :marked
@@ -451,7 +455,7 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** The Angular HTML parser is case sensitive and will recognize lower camel case.
+    **Why?** The Angular HTML parser is case sensitive and recognizes lower camel case.
 
 a(href="#toc") Back to top
 
@@ -659,7 +663,7 @@ table(width="100%")
   tr(style=top)
     td
       :marked
-        End to End Tests
+        End-to-End Tests
     td
       :marked
         app.e2e-spec.ts
@@ -765,7 +769,7 @@ a(href="#toc") Back to top
 :marked
   ## Coding conventions
 
-  Have consistent set of coding, naming, and whitespace conventions.
+  Have a consistent set of coding, naming, and whitespace conventions.
 
 .l-main-section
 :marked
@@ -824,7 +828,7 @@ a(href="#toc") Back to top
   :marked
     **Why?** The tradition of naming constants in UPPER_SNAKE_CASE reflects
     an era before the modern IDEs that quickly reveal the `const` declaration.
-    TypeScript itself prevents accidental reassignment. 
+    TypeScript prevents accidental reassignment. 
 
 .s-rule.do
   :marked
@@ -906,7 +910,7 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?** TypeScript tooling makes it easy to identify private vs public properties and methods.
+    **Why?** TypeScript tooling makes it easy to identify private vs. public properties and methods.
 
 +makeExample('style-guide/ts/src/03-04/app/core/toast.service.avoid.ts', 'example', 'app/shared/toast.service.ts')(avoid=1)
 :marked
@@ -972,10 +976,10 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** structure the app such that you can `L`ocate code quickly, 
-    `I`dentify the code at a glance, 
-    keep the `F`lattest structure you can, and 
-    `T`ry to be DRY.
+    **Do** structure the app such that you can **L**ocate code quickly, 
+    **I**dentify the code at a glance, 
+    keep the **F**lattest structure you can, and 
+    **T**ry to be DRY.
 
 .s-rule.do
   :marked
@@ -1000,8 +1004,7 @@ a(href="#toc") Back to top
 
 .s-why.s-why-last
   :marked
-    **Why?**  
-    To work efficiently you must be able to find files quickly, 
+    **Why?** To work efficiently you must be able to find files quickly, 
     especially when you do not know (or do not remember) the file _names_. 
     Keeping related files near each other in an intuitive location saves time. 
     A descriptive folder structure makes a world of difference to you and the people who come after you.
@@ -1077,7 +1080,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** be DRY (Don't Repeat Yourself)
+    **Do** be DRY (Don't Repeat Yourself).
 
 .s-rule.avoid
   :marked
@@ -1087,7 +1090,8 @@ a(href="#toc") Back to top
   :marked
     **Why?** Being DRY is important, but not crucial if it sacrifices the other elements of LIFT.
     That's why it's called _T-DRY_. 
-    For example, it's redundant to name a component, `hero-view.component.html` because a component is obviously a view. 
+    For example, it's redundant to name a template `hero-view.component.html` because 
+    with the `.html` extension, it is obviously a view. 
     But if something is not obvious or departs from a convention, then spell it out.
 
 a(href="#toc") Back to top
@@ -1203,20 +1207,23 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** A developer can locate the code, identify what each file represents 
-    at a glance, the structure is as flat as it can be, and there are no repetitive or redundant names.
+    **Why?** A developer can locate the code and identify what each file represents 
+    at a glance. The structure is as flat as it can be and there are no repetitive or redundant names.
 
 .s-why
   :marked
     **Why?** The LIFT guidelines are all covered.
 
 .s-why
   :marked
-    **Why?** Helps reduce the app from becoming cluttered through organizing the content and keeping them aligned with the LIFT guidelines.
+    **Why?** Helps reduce the app from becoming cluttered through organizing the 
+    content and keeping them aligned with the LIFT guidelines.
 
 .s-why
   :marked
-    **Why?** When there are a lot of files (e.g. 10+), locating them is easier with a consistent folder structure and more difficult in a flat structure.
+    **Why?** When there are a lot of files, for example 10+, 
+    locating them is easier with a consistent folder structure 
+    and more difficult in a flat structure.
 
 .s-rule.do
   :marked
@@ -1243,7 +1250,8 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** create an Angular module in the app's root folder (e.g., in `/src/app`).
+    **Do** create an Angular module in the app's root folder,
+    for example, in `/src/app`.
 
 .s-why
   :marked
@@ -1269,19 +1277,23 @@ a(href="#toc") Back to top
 .s-rule.do
 
   :marked
-    **Do** create an Angular module for all distinct features in an application (e.g. `Heroes` feature).
+    **Do** create an Angular module for all distinct features in an application; 
+    for example, a `Heroes` feature.
 
 .s-rule.do
   :marked
-    **Do** place the feature module in the same named folder as the feature area (.e.g `app/heroes`).
+    **Do** place the feature module in the same named folder as the feature area;
+    for example, in `app/heroes`.
 
 .s-rule.do
   :marked
-    **Do** name the feature module file reflecting the name of the feature area and folder (e.g. `app/heroes/heroes.module.ts`)
+    **Do** name the feature module file reflecting the name of the feature area 
+    and folder; for example, `app/heroes/heroes.module.ts`.
 
 .s-rule.do
   :marked
-    **Do** name the feature module symbol reflecting the name of the feature area, folder, and file (e.g. `app/heroes/heroes.module.ts` defines `HeroesModule`)
+    **Do** name the feature module symbol reflecting the name of the feature 
+    area, folder, and file; for example, `app/heroes/heroes.module.ts` defines `HeroesModule`.
 
 .s-why
   :marked
@@ -1316,7 +1328,8 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** create a feature module named `SharedModule` in a `shared` folder (e.g. `app/shared/shared.module.ts` defines `SharedModule`).
+    **Do** create a feature module named `SharedModule` in a `shared` folder; 
+    for example, `app/shared/shared.module.ts` defines `SharedModule`.
 
 .s-rule.do
   :marked
@@ -1325,7 +1338,7 @@ a(href="#toc") Back to top
 
 .s-rule.consider
   :marked
-    **Consider** using the name SharedModule, when the contents of a shared 
+    **Consider** using the name SharedModule when the contents of a shared 
     module are referenced across the entire application.
 
 .s-rule.do
@@ -1336,11 +1349,14 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** import all modules required by the assets in the `SharedModule` (e.g. `CommonModule` and `FormsModule`).
+    **Do** import all modules required by the assets in the `SharedModule`;
+    for example, `CommonModule` and `FormsModule`.
 
 .s-why
   :marked
-    **Why?** `SharedModule` will contain components, directives and pipes that may need features from another common module (e.g. `ngFor` in `CommonModule`).
+    **Why?** `SharedModule` will contain components, directives and pipes 
+    that may need features from another common module; for example, 
+    `ngFor` in `CommonModule`.
 
 .s-rule.do
   :marked
@@ -1642,7 +1658,7 @@ a(href="#toc") Back to top
   :marked
     **Why?** components have templates containing HTML and optional Angular template syntax.
     They display content. 
-    Developers place components on the page as they would native HTML elements and WebComponents.
+    Developers place components on the page as they would native HTML elements and web components.
 
 .s-why.s-why-last
   :marked
@@ -1726,7 +1742,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** use the `@Input` and `@Output` class decorators instead of the `inputs` and `outputs` properties of the 
+    **Do** use the `@Input()` and `@Output()` class decorators instead of the `inputs` and `outputs` properties of the 
     `@Directive` and `@Component` metadata:
 
 .s-rule.do
@@ -1937,7 +1953,7 @@ a(href="#toc") Back to top
 
 .s-why
   :marked
-    **Why?** Attributes directives don't have an associated template.
+    **Why?** Attribute directives don't have an associated template.
 
 .s-why.s-why-last
   :marked
@@ -1968,7 +1984,7 @@ a(href="#toc") Back to top
 .s-why.s-why-last
   :marked
     **Why?** The property associated with `@HostBinding` or the method associated with `@HostListener` 
-    can be modified only in a single place - in the directive's class. 
+    can be modified only in a single place&mdash;in the directive's class. 
     If you use the `host` metadata property, you must modify both the property declaration inside the controller, 
     and the metadata associated with the directive.
 
@@ -2075,7 +2091,7 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** use the `@Injectable` class decorator instead of the `@Inject` parameter decorator when using types as tokens for the dependencies of a service.
+    **Do** use the `@Injectable()` class decorator instead of the `@Inject` parameter decorator when using types as tokens for the dependencies of a service.
 
 .s-why
   :marked