iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

This commit is contained in:
Kapunahele Wong 2017-03-22 13:23:46 -04:00 committed by Jules Kremer
parent 0fc40284dd
commit 8d307c53da
1 changed files with 79 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
public/docs/ts/latest/guide/style-guide.jade
View File

@ -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.
.l-main-section
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,8 +1207,8 @@ 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
@ -1212,11 +1216,14 @@ a(href="#toc") Back to top
.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