docs(style-guide): edit copy #3020

kapunahelewong · 2016-12-21T18:21:35Z

Copy edits to the style guide. @wardbell I toned down some of the case recommendations but can revert if you prefer.

wardbell

Looks good. I made some more suggestions. I will unblock when you're done.

wardbell · 2017-01-02T23:55:57Z

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

    1. [Appendix](#appendix)

 .l-main-section
 :marked
  ## Single Responsibility

-  Apply the [Single Responsibility Principle](https://wikipedia.org/wiki/Single_responsibility_principle) to all components, services, and other symbols. 
+  Apply the [single responsibility principle](https://wikipedia.org/wiki/Single_responsibility_principle) to all components, services, and other symbols. 


Please revert to Single Responsibility Principle as it is known throughout the world by that name and its initials, SRP.

wardbell · 2017-01-03T00:00:17Z

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

 :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*.

 +makeExample('style-guide/ts/01-01/app/heroes/hero.component.avoid.ts', '', 'app/heroes/hero.component.ts')(avoid=1)
 :marked
-  Better to redistribute the component and supporting activities into their own dedicated files.
+  Redistributing the component and supporting activities into their own dedicated files 


I prefer the infinitive to the participle.

It is a better practice to redistribute the component and its supporting classes into their own, dedicated files.

wardbell · 2017-01-03T00:02:18Z

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

@@ -236,24 +239,20 @@ a(href="#toc") Back to top

 .s-rule.do
  :marked
-    **Do** use upper camel case for class names. Match the name of the symbol to the name of the file.
+    **Do** match the name of the symbol to the name of the file. 


Should these be two separate DOs?
Do use upper camel case for class names.
Do match the name of the symbol to the name of the file.

Good idea. Done.

wardbell · 2017-01-03T00:03:44Z

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


 .s-rule.do
  :marked
-    **Do** append the symbol name with the conventional suffix for a thing of that type 
-    (e.g., `Component`, `Directive`, `Module`, `Pipe`, `Service`).
+    **Do** append the symbol name with the conventional suffix for a thing of that type. 


I think the following is better

Do append the symbol name with the conventional suffix (such as Component, Directive, Module, Pipe, or Service) for a thing of that type.

wardbell · 2017-01-03T00:04:42Z

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


 .s-rule.do
  :marked
-    **Do** give the filename the conventional suffix for a file of that type 
-    (e.g., `.component.ts`, `.directive.ts`, `.module.ts`, `.pipe.ts`, `.service.ts`).
+    **Do** give the filename the conventional suffix for a file of that type.


I think the following is better

Do give the filename the conventional suffix (such as .component.ts, .directive.ts, .module.ts, .pipe.ts, or .service.ts ) for a file of that type.

wardbell · 2017-01-03T00:30:16Z

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

@@ -1303,7 +1299,7 @@ a(href="#toc") Back to top

 .s-rule.do
  :marked
-    **Do** put common components, directives and pipes that will be used throughout the application by other feature modules in the `SharedModule`, where those assets are expected to share a new instance of themselves (not singletons).
+    **Do** put common components, directives, and pipes that will be used throughout the application by other feature modules in the `SharedModule`, where those assets are expected to share a new instance of themselves (not singletons).


Please rewrite as follows:

Do declare components, directives, and pipes in a shared module when those items will be re-used and referenced by the components declared in other feature modules.

Consider using the name SharedModule, when the contents of a shared module are referenced across the entire application.

Do not provide services in shared modules. Services are usually singletons that are provided once for the entire application or in a particular feature module.

wardbell · 2017-01-03T00:39:49Z

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

@@ -1384,7 +1380,7 @@ a(href="#toc") Back to top

 .s-rule.do
  :marked
-    **Do** collect single-use classes and hiding their gory details inside `CoreModule`. A simplified root `AppModule` imports `CoreModule` in its capacity as orchestrator of the application as a whole.
+    **Do** collect single-use classes and hide their gory details inside `CoreModule`. A simplified root `AppModule` imports `CoreModule` in its capacity as orchestrator of the application as a whole.


Better?:

Consider collecting numerous, auxiliary, single-use classes inside a core module
to simplify the apparent structure of a feature module.

Consider calling the application-wide core module, CoreModule .
Importing CoreModule into the root AppModule reduces its complexity and emphasizes its role as orchestrator of the application as a whole.

wardbell · 2017-01-03T00:42:56Z

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

@@ -2022,7 +2019,8 @@ a(href="#toc") Back to top

 .s-why
  :marked
-    **Why?** The Angular DI mechanism resolves all dependencies of services based on their types declared with the services' constructors.
+    **Why?** The Angular Dependency Injection (DI) mechanism resolves all dependencies 
+    of services based on their types declared with the services' constructors.


Why? The Angular Dependency Injection (DI) mechanism resolves a service's own dependencies based on the declared types of that service's constructor parameters.

wardbell · 2017-01-03T00:54:53Z

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

@@ -2061,7 +2059,11 @@ a(href="#toc") Back to top

 .s-why.s-why-last
  :marked
-    **Why?** Data service implementation may have very specific code to handle the data repository. This may include headers, how to talk to the data, or other services such as `Http`. Separating the logic into a data service encapsulates this logic in a single place hiding the implementation from the outside consumers (perhaps a component), also making it easier to change the implementation.
+    **Why?** Data service implementation may have very specific code to handle the data repository. 


Replace #2062-2066

Why? The details of data management, such as headers, HTTP methods, caching, error handling, and retry logic, are irrelevant to components and other data consumers.

A data service encapsulates these details. It's easier to evolve these details inside the service without affecting its consumers. And it's easier to test the consumers with mock service implementations.

wardbell · 2017-01-03T00:56:37Z

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

@@ -2084,7 +2086,7 @@ a(href="#toc") Back to top

 .s-why.s-why-last
  :marked
-    **Why?** Strongly-typed method signatures.
+    **Why?** Lifecycle hook interfaces use strongly-typed method signatures.


Replace this line and next

Why? Lifecycle interfaces prescribe typed method signatures. use those signatures to flag spelling and syntax mistakes.

googlebot added the CLA: yes label Dec 21, 2016

kapunahelewong force-pushed the wong-style-guide branch from 6329541 to 4ffad06 Compare December 21, 2016 20:41

Foxandxss approved these changes Dec 24, 2016

View reviewed changes

wardbell suggested changes Jan 3, 2017

View reviewed changes

wardbell added the pr_state: blocked label Jan 3, 2017

kapunahelewong added 2 commits January 3, 2017 09:49

docs(style-guide): edit copy

a185cc1

docs(style-guide): copy edits

5b46b44

kapunahelewong force-pushed the wong-style-guide branch from 4ffad06 to 5b46b44 Compare January 3, 2017 18:41

wardbell approved these changes Jan 3, 2017

View reviewed changes

wardbell removed the pr_state: blocked label Jan 3, 2017

wardbell merged commit 6d431f1 into angular:master Jan 3, 2017

wardbell deleted the wong-style-guide branch January 3, 2017 20:44

abdel-ships-it pushed a commit to abdel-ships-it/angular.io that referenced this pull request Feb 11, 2017

docs(style-guide): edit copy (angular#3020)

c611e29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(style-guide): edit copy #3020

docs(style-guide): edit copy #3020

kapunahelewong commented Dec 21, 2016

wardbell left a comment •

edited

Loading

wardbell Jan 2, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

wardbell Jan 3, 2017

kapunahelewong Jan 3, 2017

docs(style-guide): edit copy #3020

docs(style-guide): edit copy #3020

Conversation

kapunahelewong commented Dec 21, 2016

wardbell left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wardbell left a comment •

edited

Loading