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

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

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