docs(style-guide): spell const variables in lower camel case

Changes previous guidance on const which insisted on UPPER_SNAKE_CASE

Author: wardbell

public/docs/_examples/style-guide/ts/03-02/app/app.component.ts

@@ -1,15 +1,19 @@
 import { Component } from '@angular/core';
 
-import { HEROES_URL, VILLAINS_URL } from './shared';
+import { heroesUrl, mockHeroes, VILLAINS_URL } from './shared';
 
 @Component({
   selector: 'sg-app',
   template: `
     <div>Heroes url: {{heroesUrl}}</div>
     <div>Villains url: {{villainsUrl}}</div>
-  `,
+
+    <h4>Mock Heroes</h4>
+    <div *ngFor="let hero of heroes">{{hero}}</div>
+  `
 })
 export class AppComponent {
-  heroesUrl = HEROES_URL;
-  villainsUrl = VILLAINS_URL;
+  heroes      = mockHeroes;   // prefer
+  heroesUrl   = heroesUrl;    // prefer
+  villainsUrl = VILLAINS_URL; // tolerate
 }

public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.avoid.ts

@@ -1,5 +1,4 @@
 // #docregion
-// #docregion example
-export const HEROES_URL = 'api/heroes';
-export const VILLAINS_URL = 'api/villains';
-// #enddocregion example
+export const mockHeroes   = ['Sam', 'Jill']; // prefer
+export const heroesUrl    = 'api/heroes';    // prefer
+export const VILLAINS_URL = 'api/villains';  // tolerate

public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.ts

@@ -651,20 +651,43 @@ a(href="#toc") Back to top
 
 .s-rule.do
   :marked
-    **Do** use uppercase with underscores when naming constants.
+    **Do** declare variables with `const` if their values should not change during the application lifetime.
 
 .s-why
   :marked
-    **Why?** Follows conventional thinking for constants.
+    **Why?** Conveys to readers that the value is invariant.
 
 .s-why.s-why-last
   :marked
-    **Why?** Constants can easily be identified.
+    TypeScript helps enforce that intent by requiring immediate initialization and by
+    preventing subsequent re-assignment.
+    
+.s-rule.consider
+  :marked
+    **Consider** spelling `const` variables in lower camel case.
 
-+makeExample('style-guide/ts/03-02/app/shared/data.service.avoid.ts', 'example', 'app/shared/data.service.ts')(avoid=1)
-:marked
+.s-why
+  :marked
+    **Why?** lower camel case variable names (`heroRoutes`) are easier to read and understand
+    than the traditional UPPER_SNAKE_CASE names (`HERO_ROUTES`).
+
+.s-why.s-why-last
+  :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. 
+    
+.s-rule.do
+  :marked
+    **Do** tolerate _existing_ `const` variables that are spelled in UPPER_SNAKE_CASE.
+
+.s-why.s-why-last
+  :marked
+    **Why?** Although we recommend creating _new_ constants in lower camel case,
+    the tradition of UPPER_SNAKE_CASE remains popular and pervasive,
+    especially in third party modules.
 
-+makeExample('style-guide/ts/03-02/app/shared/data.service.ts', 'example', 'app/shared/data.service.ts')
++makeExample('style-guide/ts/03-02/app/shared/data.service.ts', '', 'app/shared/data.service.ts')
 :marked
 
 a(href="#toc") Back to top