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

aio(style-guide): adjust to support migration to aio (#3490)

This commit is contained in:
Ward Bell 2017-04-01 15:13:42 -07:00 committed by GitHub
parent 58e5fbe007
commit 914823a47a
2 changed files with 113 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -6,7 +6,7 @@ include ../_util-fns
This style guide presents preferred conventions and, as importantly, explains why.
.l-main-section
a(id='toc')
a#toc
:marked
# Contents
@ -22,7 +22,6 @@ a(id='toc')
* [Lifecycle hooks](#lifecycle-hooks)
* [Appendix](#appendix)
.l-main-section
:marked
## Style vocabulary
@ -71,9 +70,10 @@ a#single-responsibility
to all components, services, and other symbols.
This helps make the app cleaner, easier to read and maintain, and more testable.
### <a id="01-01"></a>Rule of One
#### <a href="#01-01">Style 01-01</a>
.s-rule.do
:marked
**Do** define one thing, such as a service or component, per file.
@ -91,7 +91,7 @@ a#single-responsibility
:marked
**Why?** One component per file avoids hidden bugs that often arise when combining components in a file where they may share variables, create unwanted closures, or unwanted coupling with dependencies.
.s-why.s-why-last
.s-why-last
:marked
**Why?** A single component can be the default export for its file which facilitates lazy loading with the router.
:marked
@ -131,7 +131,9 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="01-02"></a>Small functions
#### <a href="#01-02">Style 01-02</a>
.s-rule.do
:marked
**Do** define small functions
@ -156,7 +158,7 @@ a(href="#toc") Back to top
:marked
**Why?** Small functions are easier to maintain.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Small functions help avoid hidden bugs that come with large functions that share variables with external scope, create unwanted closures, or unwanted coupling with dependencies.
@ -171,6 +173,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-01"></a>General Naming Guidelines
#### <a href="#02-01">Style 02-01</a>
.s-rule.do
@ -189,7 +192,7 @@ a(href="#toc") Back to top
:marked
**Why?** The naming conventions should simply help find desired code faster and make it easier to understand.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Names of folders and files should clearly convey their intent. For example, `app/heroes/hero-list.component.ts` may contain a component that manages a list of heroes.
@ -198,6 +201,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-02"></a>Separate file names with dots and dashes
#### <a href="#02-02">Style 02-02</a>
.s-rule.do
@ -230,7 +234,7 @@ a(href="#toc") Back to top
**Why?** Unabbreviated type names such as `.service` are descriptive and unambiguous.
Abbreviations such as `.srv`, `.svc`, and `.serv` can be confusing.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Type names provide pattern matching for any automated tasks.
@ -239,6 +243,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-03"></a>Symbols and file names
#### <a href="#02-03">Style 02-03</a>
.s-rule.do
@ -345,6 +350,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-04"></a>Service names
#### <a href="#02-04">Style 02-04</a>
.s-rule.do
@ -371,7 +377,7 @@ a(href="#toc") Back to top
:marked
**Why?** Clear service names such as `Logger` do not require a suffix.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Service names such as `Credit` are nouns and require a suffix and should be named with a suffix when it is not obvious if it is a service or something else.
@ -413,6 +419,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-05"></a>Bootstrapping
#### <a href="#02-05">Style 02-05</a>
.s-rule.do
@ -431,7 +438,7 @@ a(href="#toc") Back to top
:marked
**Why?** Follows a consistent convention for the startup logic of an app.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Follows a familiar convention from other technology platforms.
@ -443,6 +450,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-06"></a>Directive selectors
#### <a href="#02-06">Style 02-06</a>
.s-rule.do
@ -453,7 +461,7 @@ a(href="#toc") Back to top
:marked
**Why?** Keeps the names of the properties defined in the directives that are bound to the view consistent with the attribute names.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The Angular HTML parser is case sensitive and recognizes lower camel case.
@ -462,6 +470,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-07"></a>Custom prefix for components
#### <a href="#02-07">Style 02-07</a>
.s-rule.do
@ -486,7 +495,7 @@ a(href="#toc") Back to top
:marked
**Why?** Makes it easier to promote and share the component in other apps.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Components are easy to identify in the DOM.
@ -504,6 +513,7 @@ a(href="#toc") Back to top
:marked
### <a id="02-08"></a>Custom prefix for directives
#### <a href="#02-08">Style 02-08</a>
.s-rule.do
@ -518,7 +528,7 @@ a(href="#toc") Back to top
:marked
**Why?** Prevents name collisions.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Directives are easily identified.
@ -533,13 +543,14 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-09"></a>Pipe names
#### <a href="#02-09">Style 02-09</a>
.s-rule.do
:marked
**Do** use consistent names for all pipes, named after their feature.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Provides a consistent way to quickly identify and reference pipes.
@ -573,6 +584,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-10"></a>Unit test file names
#### <a href="#02-10">Style 02-10</a>
.s-rule.do
@ -587,7 +599,7 @@ a(href="#toc") Back to top
:marked
**Why?** Provides a consistent way to quickly identify tests.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Provides pattern matching for [karma](http://karma-runner.github.io/) or other test runners.
@ -637,6 +649,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-11"></a>_End-to-End_ (E2E) test file names
#### <a href="#02-11">Style 02-11</a>
.s-rule.do
@ -647,7 +660,7 @@ a(href="#toc") Back to top
:marked
**Why?** Provides a consistent way to quickly identify end-to-end tests.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Provides pattern matching for test runners and build automation.
@ -676,6 +689,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="02-12"></a>Angular _NgModule_ names
#### <a href="#02-12">Style 02-12</a>
.s-rule.do
@ -698,7 +712,7 @@ a(href="#toc") Back to top
:marked
**Why?** Upper camel case is conventional for identifying objects that can be instantiated using a constructor.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Easily identifies the module as the root of the same named feature.
@ -710,7 +724,7 @@ a(href="#toc") Back to top
:marked
**Do** end the filename of a _RoutingModule_ with `-routing.module.ts`.
.s-why.s-why-last
.s-why-last
:marked
**Why?** A `RoutingModule` is a module dedicated exclusively to configuring the Angular router.
A consistent class and file name convention make these modules easy to spot and verify.
@ -774,6 +788,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="03-01"></a>Classes
#### <a href="#03-01">Style 03-01</a>
.s-rule.do
@ -784,7 +799,7 @@ a(href="#toc") Back to top
:marked
**Why?** Follows conventional thinking for class names.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Classes can be instantiated and construct an instance.
By convention, upper camel case indicates a constructable asset.
@ -800,6 +815,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="03-02"></a>Constants
#### <a href="#03-02">Style 03-02</a>
.s-rule.do
@ -810,7 +826,7 @@ a(href="#toc") Back to top
:marked
**Why?** Conveys to readers that the value is invariant.
.s-why.s-why-last
.s-why-last
:marked
**Why?** TypeScript helps enforce that intent by requiring immediate initialization and by
preventing subsequent re-assignment.
@ -824,7 +840,7 @@ a(href="#toc") Back to top
**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
.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.
@ -834,7 +850,7 @@ a(href="#toc") Back to top
:marked
**Do** tolerate _existing_ `const` variables that are spelled in UPPER_SNAKE_CASE.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The tradition of UPPER_SNAKE_CASE remains popular and pervasive,
especially in third party modules.
@ -848,6 +864,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="03-03"></a>Interfaces
#### <a href="#03-03">Style 03-03</a>
.s-rule.do
@ -875,7 +892,7 @@ a(href="#toc") Back to top
:marked
**Why?** A class can act as an interface (use `implements` instead of `extends`).
.s-why.s-why-last
.s-why-last
:marked
**Why?** An interface-class can be a provider lookup token in Angular dependency injection.
@ -890,6 +907,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="03-04"></a>Properties and methods
#### <a href="#03-04">Style 03-04</a>
.s-rule.do
@ -908,7 +926,7 @@ a(href="#toc") Back to top
:marked
**Why?** JavaScript lacks a true private property or method.
.s-why.s-why-last
.s-why-last
:marked
**Why?** TypeScript tooling makes it easy to identify private vs. public properties and methods.
@ -923,6 +941,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="03-06"></a>Import line spacing
#### <a href="#03-06">Style 03-06</a>
.s-rule.consider
@ -941,7 +960,7 @@ a(href="#toc") Back to top
:marked
**Why?** The empty line separates _your_ stuff from _their_ stuff.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Alphabetizing makes it easier to read and locate symbols.
@ -972,6 +991,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-01"></a>_LIFT_
#### <a href="#04-01">Style 04-01</a>
.s-rule.do
@ -985,7 +1005,7 @@ a(href="#toc") Back to top
:marked
**Do** define the structure to follow these four basic guidelines, listed in order of importance.
.s-why.s-why-last
.s-why-last
:marked
**Why?** LIFT Provides a consistent structure that scales well, is modular, and makes it easier to increase developer efficiency by finding code quickly.
To confirm your intuition about a particular structure, ask:
@ -996,13 +1016,14 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-02"></a>Locate
#### <a href="#04-02">Style 04-02</a>
.s-rule.do
:marked
**Do** make locating code intuitive, simple and fast.
.s-why.s-why-last
.s-why-last
:marked
**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_.
@ -1014,6 +1035,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-03"></a>Identify
#### <a href="#04-03">Style 04-03</a>
.s-rule.do
@ -1028,7 +1050,7 @@ a(href="#toc") Back to top
:marked
**Avoid** files with multiple components, multiple services, or a mixture.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Spend less time hunting and pecking for code, and become more efficient.
Longer file names are far better than _short-but-obscure_ abbreviated names.
@ -1044,6 +1066,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-04"></a>Flat
#### <a href="#04-04">Style 04-04</a>
.s-rule.do
@ -1058,7 +1081,7 @@ a(href="#toc") Back to top
:marked
**Consider** configuring the IDE to hide distracting, irrelevant files such as generated `.js` and `.js.map` files.
.s-why.s-why-last
.s-why-last
:marked
**Why?** No one wants to search for a file through seven levels of folders.
A flat structure is easy to scan.
@ -1076,6 +1099,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-05"></a>_T-DRY_ (Try to be _DRY_)
#### <a href="#04-05">Style 04-05</a>
.s-rule.do
@ -1086,7 +1110,7 @@ a(href="#toc") Back to top
:marked
**Avoid** being so DRY that you sacrifice readability.
.s-why.s-why-last
.s-why-last
: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_.
@ -1099,6 +1123,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-06"></a>Overall structural guidelines
#### <a href="#04-06">Style 04-06</a>
.s-rule.do
@ -1121,7 +1146,7 @@ a(href="#toc") Back to top
:marked
**Why?** Helps keep the app structure small and easy to maintain in the early stages, while being easy to evolve as the app grows.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Components often have four files (e.g. `*.html`, `*.css`, `*.ts`, and `*.spec.ts`) and can clutter a folder quickly.
@ -1199,6 +1224,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-07"></a>_Folders-by-feature_ structure
#### <a href="#04-07">Style 04-07</a>
.s-rule.do
@ -1233,7 +1259,7 @@ a(href="#toc") Back to top
:marked
**Why?** Angular modules make it easy to lazy load routable features.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Angular modules make it easier to isolate, test, and re-use features.
@ -1246,6 +1272,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-08"></a>App _root module_
#### <a href="#04-08">Style 04-08</a>
.s-rule.do
@ -1261,7 +1288,7 @@ a(href="#toc") Back to top
:marked
**Consider** naming the root module `app.module.ts`.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Makes it easier to locate and identify the root module.
@ -1273,7 +1300,9 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-09"></a>Feature modules
#### <a href="#04-09">Style 04-09</a>
.s-rule.do
:marked
@ -1315,7 +1344,7 @@ a(href="#toc") Back to top
:marked
**Why?** A feature module helps clarify and make it easier to assign development responsibilities to different teams.
.s-why.s-why-last
.s-why-last
:marked
**Why?** A feature module can easily be isolated for testing.
@ -1324,6 +1353,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-10"></a>Shared feature module
#### <a href="#04-10">Style 04-10</a>
.s-rule.do
@ -1378,7 +1408,7 @@ a(href="#toc") Back to top
:marked
**Why?** A lazy loaded feature module that imports that shared module will make its own copy of the service and likely have undesireable results.
.s-why.s-why-last
.s-why-last
:marked
**Why?** You don't want each module to have its own separate instance of singleton services.
Yet there is a real danger of that happening if the `SharedModule` provides a service.
@ -1425,6 +1455,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-11"></a>Core feature module
#### <a href="#04-11">Style 04-11</a>
.s-rule.consider
@ -1489,7 +1520,7 @@ a(href="#toc") Back to top
:marked
**Why?** `CoreModule` exists to make commonly used singleton services available for use in the many other modules.
.s-why.s-why-last
.s-why-last
:marked
**Why?** You want the entire app to use the one, singleton instance.
You don't want each module to have its own separate instance of singleton services.
@ -1556,7 +1587,9 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-12"></a>Prevent re-import of the core module
#### <a href="#04-12">Style 04-12</a>
Only the root `AppModule` should import the `CoreModule`.
.s-rule.do
@ -1567,7 +1600,7 @@ a(href="#toc") Back to top
:marked
**Why?** Guards against reimporting of the `CoreModule`.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Guards against creating multiple instances of assets intended to be singletons.
@ -1588,7 +1621,9 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-13"></a>Lazy Loaded folders
#### <a href="#04-13">Style 04-13</a>
A distinct application feature or workflow may be *lazy loaded* or *loaded on demand* rather than when the application starts.
.s-rule.do
@ -1596,7 +1631,7 @@ a(href="#toc") Back to top
**Do** put the contents of lazy loaded features in a *lazy loaded folder*.
A typical *lazy loaded folder* contains a *routing component*, its child components, and their related assets and modules.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The folder makes it easy to identify and isolate the feature content.
@ -1605,13 +1640,14 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="04-14"></a>Never directly import lazy loaded folders
#### <a href="#04-14">Style 04-14</a>
.s-rule.avoid
:marked
**Avoid** allowing modules in sibling and parent folders to directly import a module in a *lazy loaded feature*.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Directly importing and using a module will load it immediately when the intention is to load it on demand.
@ -1622,13 +1658,14 @@ a(href="#toc") Back to top
## Components
### <a id="05-02"></a>Component selector names
#### <a href="#05-02">Style 05-02</a>
.s-rule.do
:marked
**Do** use _dashed-case_ or _kebab-case_ for naming the element selectors of components.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Keeps the element names consistent with the specification for [Custom Elements](https://www.w3.org/TR/custom-elements/).
@ -1648,6 +1685,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-03"></a>Components as elements
#### <a href="#05-03">Style 05-03</a>
.s-rule.do
@ -1660,7 +1698,7 @@ a(href="#toc") Back to top
They display content.
Developers place components on the page as they would native HTML elements and web components.
.s-why.s-why-last
.s-why-last
:marked
**Why?** It is easier to recognize that a symbol is a component by looking at the template's html.
@ -1683,6 +1721,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-04"></a>Extract templates and styles to their own files
#### <a href="#05-04">Style 05-04</a>
.s-rule.do
@ -1715,7 +1754,7 @@ a(href="#toc") Back to top
:marked
**Why?** A _component relative_ URL requires no change when you move the component files, as long as the files stay together.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The `./` prefix is standard syntax for relative URLs; don't depend on Angular's current ability to do without that prefix.
@ -1738,6 +1777,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-12"></a>Decorate _input_ and _output_ properties
#### <a href="#05-12">Style 05-12</a>
.s-rule.do
@ -1762,7 +1802,7 @@ a(href="#toc") Back to top
:marked
**Why?** The metadata declaration attached to the directive is shorter and thus more readable.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Placing the decorator on the same line _usually_ makes for shorter code and still easily identifies the property as an input or output.
Put it on the line above when doing so is clearly more readable.
@ -1778,6 +1818,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-13"></a>Avoid aliasing _inputs_ and _outputs_
#### <a href="#05-13">Style 05-13</a>
.s-rule.avoid
@ -1788,7 +1829,7 @@ a(href="#toc") Back to top
:marked
**Why?** Two names for the same property (one private, one public) is inherently confusing.
.s-why.s-why-last
.s-why-last
:marked
**Why?** You should use an alias when the directive name is also an _input_ property,
and the directive name doesn't describe the property.
@ -1814,6 +1855,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-14"></a>Member sequence
#### <a href="#05-14">Style 05-14</a>
.s-rule.do
@ -1824,7 +1866,7 @@ a(href="#toc") Back to top
:marked
**Do** place private members after public members, alphabetized.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Placing members in a consistent sequence makes it easy to read and
helps instantly identify which members of the component serve which purpose.
@ -1840,6 +1882,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-15"></a>Delegate complex component logic to services
#### <a href="#05-15">Style 05-15</a>
.s-rule.do
@ -1862,7 +1905,7 @@ a(href="#toc") Back to top
:marked
**Why?** Removes dependencies and hides implementation details from the component.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Keeps the component slim, trim, and focused.
@ -1877,6 +1920,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-16"></a>Don't prefix _output_ properties
#### <a href="#05-16">Style 05-16</a>
.s-rule.do
@ -1891,7 +1935,7 @@ a(href="#toc") Back to top
:marked
**Why?** This is consistent with built-in events such as button clicks.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Angular allows for an [alternative syntax](template-syntax.html#binding-syntax) `on-*`. If the event itself was prefixed with `on` this would result in an `on-onEvent` binding expression.
@ -1914,6 +1958,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="05-17"></a>Put presentation logic in the component class
#### <a href="#05-17">Style 05-17</a>
.s-rule.do
@ -1924,7 +1969,7 @@ a(href="#toc") Back to top
:marked
**Why?** Logic will be contained in one place (the component class) instead of being spread in two places.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Keeping the component's presentation logic in the class instead of the template improves testability, maintainability, and reusability.
@ -1943,6 +1988,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="06-01"></a>Use directives to enhance an element
#### <a href="#06-01">Style 06-01</a>
.s-rule.do
@ -1953,7 +1999,7 @@ a(href="#toc") Back to top
:marked
**Why?** Attribute directives don't have an associated template.
.s-why.s-why-last
.s-why-last
:marked
**Why?** An element may have more than one attribute directive applied.
@ -1968,6 +2014,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="06-03"></a>_HostListener_/_HostBinding_ decorators versus _host_ metadata
#### <a href="#06-03">Style 06-03</a>
.s-rule.consider
@ -1979,7 +2026,7 @@ a(href="#toc") Back to top
:marked
**Do** be consistent in your choice.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The property associated with `@HostBinding` or the method associated with `@HostListener`
can be modified only in a single place&mdash;in the directive's class.
@ -1990,7 +2037,7 @@ a(href="#toc") Back to top
:marked
Compare with the less preferred `host` metadata alternative.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The `host` metadata is only one term to remember and doesn't require extra ES imports.
@ -2004,6 +2051,7 @@ a(href="#toc") Back to top
## Services
### <a id="07-01"></a>Services are singletons
#### <a href="#07-01">Style 07-01</a>
.s-rule.do
@ -2014,7 +2062,7 @@ a(href="#toc") Back to top
:marked
**Why?** Services are ideal for sharing methods across a feature area or an app.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Services are ideal for sharing stateful in-memory data.
@ -2026,6 +2074,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="07-02"></a>Single responsibility
#### <a href="#07-02">Style 07-02</a>
.s-rule.do
@ -2040,7 +2089,7 @@ a(href="#toc") Back to top
:marked
**Why?** When a service has multiple responsibilities, it becomes difficult to test.
.s-why.s-why-last
.s-why-last
:marked
**Why?** When a service has multiple responsibilities, every component or service that injects it now carries the weight of them all.
@ -2049,6 +2098,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="07-03"></a>Providing a service
#### <a href="#07-03">Style 07-03</a>
.s-rule.do
@ -2068,7 +2118,7 @@ a(href="#toc") Back to top
:marked
**Why?** This is ideal when a service is sharing methods or state.
.s-why.s-why-last
.s-why-last
:marked
**Why?** This is not ideal when two different components need different instances of a service. In this scenario it would be better to provide the service at the component level that needs the new and separate instance.
@ -2085,6 +2135,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="07-04"></a>Use the @Injectable() class decorator
#### <a href="#07-04">Style 07-04</a>
.s-rule.do
@ -2096,7 +2147,7 @@ a(href="#toc") Back to top
**Why?** The Angular Dependency Injection (DI) mechanism resolves a service's own
dependencies based on the declared types of that service's constructor parameters.
.s-why.s-why-last
.s-why-last
:marked
**Why?** When a service accepts only dependencies associated with type tokens, the `@Injectable()` syntax is much less verbose compared to using `@Inject()` on each individual constructor parameter.
@ -2113,6 +2164,7 @@ a(href="#toc") Back to top
## Data Services
### <a id="08-01"></a>Talk to the server through a service
#### <a href="#08-01">Style 08-01</a>
.s-rule.do
@ -2131,7 +2183,7 @@ a(href="#toc") Back to top
:marked
**Why?** This makes it easier to test (mock or real) the data calls when testing a component that uses a data service.
.s-why.s-why-last
.s-why-last
:marked
**Why?** The details of data management, such as headers, HTTP methods,
caching, error handling, and retry logic, are irrelevant to components
@ -2154,13 +2206,14 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="09-01"></a>Implement lifecycle hook interfaces
#### <a href="#09-01">Style 09-01</a>
.s-rule.do
:marked
**Do** implement the lifecycle hook interfaces.
.s-why.s-why-last
.s-why-last
:marked
**Why?** Lifecycle interfaces prescribe typed method
signatures. use those signatures to flag spelling and syntax mistakes.
@ -2184,6 +2237,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="A-01"></a>Codelyzer
#### <a href="#A-01">Style A-01</a>
.s-rule.do
@ -2199,6 +2253,7 @@ a(href="#toc") Back to top
.l-main-section
:marked
### <a id="A-02"></a>File templates and snippets
#### <a href="#A-02">Style A-02</a>
.s-rule.do

4
public/resources/css/module/_style-guide.scss
View File

@ -23,7 +23,7 @@
border-left-color: #E0343D;
}
.s-why {
.s-why, .s-why-last {
margin-left: 12px;
padding: 0 16px;
font-size: 14px;
@ -37,7 +37,7 @@
border-left-color: #EEE;
}
.s-why.s-why-last {
.s-why-last {
margin-bottom:32px;
}