From 0664a271baaaa115bec0a8525eccaad5baf133d3 Mon Sep 17 00:00:00 2001
From: Ward Bell <wardbell@hotmail.com>
Date: Thu, 7 Jul 2016 15:27:15 -0700
Subject: [PATCH] docs(style-guide): spell const variables in lower camel case
 Changes previous guidance on const which insisted on UPPER_SNAKE_CASE

---
 .../style-guide/ts/03-02/app/app.component.ts | 12 ++++---
 .../ts/03-02/app/shared/data.service.avoid.ts |  7 ----
 .../ts/03-02/app/shared/data.service.ts       |  7 ++--
 public/docs/ts/latest/guide/style-guide.jade  | 35 +++++++++++++++----
 4 files changed, 40 insertions(+), 21 deletions(-)
 delete mode 100644 public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.avoid.ts

diff --git a/public/docs/_examples/style-guide/ts/03-02/app/app.component.ts b/public/docs/_examples/style-guide/ts/03-02/app/app.component.ts
index 15ccb3c351..cb62984849 100644
--- a/public/docs/_examples/style-guide/ts/03-02/app/app.component.ts
+++ b/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
 }
diff --git a/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.avoid.ts b/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.avoid.ts
deleted file mode 100644
index 49d5cb0d35..0000000000
--- a/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.avoid.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-// #docregion
-// #docregion example
-/* avoid */
-
-export const heroesUrl = 'api/heroes';
-export const villainsUrl = 'api/villains';
-// #enddocregion example
diff --git a/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.ts b/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.ts
index ad665a99c2..5c26478c7b 100644
--- a/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.ts
+++ b/public/docs/_examples/style-guide/ts/03-02/app/shared/data.service.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
diff --git a/public/docs/ts/latest/guide/style-guide.jade b/public/docs/ts/latest/guide/style-guide.jade
index 753c8d9b6d..e24feff721 100644
--- a/public/docs/ts/latest/guide/style-guide.jade
+++ b/public/docs/ts/latest/guide/style-guide.jade
@@ -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`).
 
-+makeExample('style-guide/ts/03-02/app/shared/data.service.ts', 'example', 'app/shared/data.service.ts')
+.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', '', 'app/shared/data.service.ts')
 :marked
 
 a(href="#toc") Back to top