-
-
**Do** is one that should always be followed.
_Always_ might be a bit too strong of a word.
Guidelines that literally should always be followed are extremely rare.
On the other hand, you need a really unusual case for breaking a *Do* guideline.
-
-
-
-
-
**Consider** guidelines should generally be followed.
If you fully understand the meaning behind the guideline and have a good reason to deviate, then do so. Please strive to be consistent.
-
-
-
-
-
**Avoid** indicates something you should almost never do. Code examples to *avoid* have an unmistakable red header.
-
-
-
-
-
**Do** define one thing, such as a service or component, per file.
@@ -858,11 +829,8 @@ As always, strive for consistency.
-
-
Back to top
-
{@a 02-05}
### Bootstrapping
@@ -872,65 +840,39 @@ As always, strive for consistency.
-
-
**Do** put bootstrapping and platform logic for the app in a file named `main.ts`.
-
-
-
-
-
**Do** include error handling in the bootstrapping logic.
-
-
-
-
-
**Avoid** putting app logic in `main.ts`. Instead, consider placing it in a component or service.
-
-
-
-
-
**Why?** Follows a consistent convention for the startup logic of an app.
-
-
-
-
-
**Why?** Follows a familiar convention from other technology platforms.
-
-
-
-
Back to top
{@a 05-02}
@@ -939,37 +881,22 @@ As always, strive for consistency.
#### Style 05-02
-
-
-
**Do** use _dashed-case_ or _kebab-case_ for naming the element selectors of components.
-
-
-
-
-
**Why?** Keeps the element names consistent with the specification for [Custom Elements](https://www.w3.org/TR/custom-elements/).
-
-
-
-
-
-
-
@@ -982,8 +909,6 @@ As always, strive for consistency.
-
-
Back to top
{@a 02-07}
@@ -995,142 +920,86 @@ As always, strive for consistency.
-
-
-**Do** use a hyphenated, lowercase element selector value (e.g. `admin-users`).
-
-
+**Do** use a hyphenated, lowercase element selector value; for example, `admin-users`.
-
-
-
-
**Do** use a custom prefix for a component selector.
For example, the prefix `toh` represents from **T**our **o**f **H**eroes and the prefix `admin` represents an admin feature area.
-
-
-
-
-
**Do** use a prefix that identifies the feature area or the app itself.
-
-
-
-
-
**Why?** Prevents element name collisions with components in other apps and with native HTML elements.
-
-
-
-
-
**Why?** Makes it easier to promote and share the component in other apps.
-
-
-
-
-
**Why?** Components are easy to identify in the DOM.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Back to top
+
{@a 02-06}
### Directive selectors
#### Style 02-06
-
-
-
**Do** Use lower camel case for naming the selectors of directives.
-
-
-
-
-
**Why?** Keeps the names of the properties defined in the directives that are bound to the view consistent with the attribute names.
-
-
-
-
-
**Why?** The Angular HTML parser is case sensitive and recognizes lower camel case.
-
+
+
Back to top
{@a 02-08}
@@ -1749,6 +1618,396 @@ A consistent class and file name convention make these modules easy to spot and
+
+
Back to top
+
+
+## Coding conventions
+
+Have a consistent set of coding, naming, and whitespace conventions.
+
+{@a 03-01}
+
+### Classes
+
+#### Style 03-01
+
+
+
+**Do** use upper camel case, also known as PascalCase, when naming classes.
+
+
+
+
+
+**Why?** Follows conventional thinking for class names.
+
+
+
+
+
+**Why?** Classes can be instantiated and construct an instance.
+By convention, upper camel case indicates a constructable asset.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Back to top
+
+
+{@a 03-02}
+
+### Constants
+
+#### Style 03-02
+
+
+
+**Do** declare variables with `const` if their values should not change during the application lifetime.
+
+
+
+
+
+**Why?** Conveys to readers that the value is invariant.
+
+
+
+
+
+
+
+**Why?** TypeScript helps enforce that intent by requiring immediate initialization and by
+preventing subsequent re-assignment.
+
+
+
+
+
+
+
+**Consider** spelling `const` variables in lower camel case.
+
+
+
+
+
+
+
+**Why?** Lower camel case variable names (`heroRoutes`) are easier to read and understand
+than the traditional UPPER_SNAKE_CASE names (`HERO_ROUTES`).
+
+
+
+
+
+
+
+**Why?** The tradition of naming constants in UPPER_SNAKE_CASE reflects
+an era before the modern IDEs that quickly reveal the `const` declaration.
+TypeScript prevents accidental reassignment.
+
+
+
+
+
+
+
+**Do** tolerate _existing_ `const` variables that are spelled in UPPER_SNAKE_CASE.
+
+
+
+
+
+**Why?** The tradition of UPPER_SNAKE_CASE remains popular and pervasive,
+especially in third party modules.
+It is rarely worth the effort to change them at the risk of breaking existing code and documentation.
+
+
+
+
+
+
+
+
+
+
Back to top
+
+
+{@a 03-03}
+
+### Interfaces
+
+#### Style 03-03
+
+
+
+
+
+**Do** name an interface using upper camel case.
+
+
+
+
+
+
+
+
+
+
+**Consider** naming an interface without an `I` prefix.
+
+
+
+
+
+
+
+
+
+
+**Consider** using a class instead of an interface for services and declarables (components, directives, and pipes).
+
+
+
+
+
+
+
+
+
+
+**Consider** using an interface for data models.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+**Why?** A class alone is less code than a _class-plus-interface_.
+
+
+
+
+
+
+
+
+
+
+**Why?** A class can act as an interface (use `implements` instead of `extends`).
+
+
+
+
+
+
+
+
+
+
+**Why?** An interface-class can be a provider lookup token in Angular dependency injection.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Back to top
+
+{@a 03-04}
+
+### Properties and methods
+
+#### Style 03-04
+
+
+
+
+
+
+**Do** use lower camel case to name properties and methods.
+
+
+
+
+
+
+
+
+
+
+**Avoid** prefixing private properties and methods with an underscore.
+
+
+
+
+
+
+
+
+
+
+**Why?** Follows conventional thinking for properties and methods.
+
+
+
+
+
+
+
+
+
+
+**Why?** JavaScript lacks a true private property or method.
+
+
+
+
+
+
+
+
+
+
+**Why?** TypeScript tooling makes it easy to identify private vs. public properties and methods.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Back to top
+
+{@a 03-06}
+
+### Import line spacing
+
+#### Style 03-06
+
+
+
+
+
+
+**Consider** leaving one empty line between third party imports and application imports.
+
+
+
+
+
+
+
+
+
+
+**Consider** listing import lines alphabetized by the module.
+
+
+
+
+
+
+
+
+
+
+**Consider** listing destructured imported symbols alphabetically.
+
+
+
+
+
+
+
+
+
+
+**Why?** The empty line separates _your_ stuff from _their_ stuff.
+
+
+
+
+
+
+
+
+
+
+**Why?** Alphabetizing makes it easier to read and locate symbols.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Back to top
@@ -2341,98 +2600,60 @@ Whatever you choose, be consistent.
-
-
**Do** create folders named for the feature area they represent.
-
-
-
-
-
**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.
-
-
-
-
-
**Why?** The LIFT guidelines are all covered.
-
-
-
-
-
**Why?** Helps reduce the app from becoming cluttered through organizing the
content and keeping them aligned with the LIFT guidelines.
-
-
-
-
-
**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.
-
-
-
-
-
**Do** create an NgModule for each feature area.
-
-
-
-
-
**Why?** NgModules make it easy to lazy load routable features.
-
-
-
-
-
**Why?** NgModules make it easier to isolate, test, and reuse features.
-
+
+ For more information, refer to
this folder and file structure example.
-
Back to top
@@ -2871,330 +3092,28 @@ Yet there is a real danger of that happening if the `SharedModule` provides a se
+
Back to top
{@a 04-11}
-### Core feature module
+### Lazy Loaded folders
#### Style 04-11
-
-
-
-
-
-**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.
-
-
-
-
+A distinct application feature or workflow may be *lazy loaded* or *loaded on demand* rather than when the application starts.
-
-
-**Do** create a feature module named `CoreModule` in a `core` folder (e.g. `app/core/core.module.ts` defines `CoreModule`).
-
+**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.
-
-
-
-
-
-
-**Do** put a singleton service whose instance will be shared throughout the application in the `CoreModule` (e.g. `ExceptionService` and `LoggerService`).
-
-
-
-
-
-
-
-
-
-
-**Do** import all modules required by the assets in the `CoreModule` (e.g. `CommonModule` and `FormsModule`).
-
-
-
-
-
-
-
-
-
-
-**Why?** `CoreModule` provides one or more singleton services. Angular registers the providers with the app root injector, making a singleton instance of each service available to any component that needs them, whether that component is eagerly or lazily loaded.
-
-
-
-
-
-
-
-
-
-
-**Why?** `CoreModule` will contain singleton services. When a lazy loaded module imports these, it will get a new instance and not the intended app-wide singleton.
-
-
-
-
-
-
-
-
-
-
-**Do** gather application-wide, single use components in the `CoreModule`.
-Import it once (in the `AppModule`) when the app starts and never import it anywhere else. (e.g. `NavComponent` and `SpinnerComponent`).
-
-
-
-
-
-
-
-
-
-
-**Why?** Real world apps can have several single-use components (e.g., spinners, message toasts, and modal dialogs) that appear only in the `AppComponent` template.
-They are not imported elsewhere so they're not shared in that sense.
-Yet they're too big and messy to leave loose in the root folder.
-
-
-
-
-
-
-
-
-
-
-**Avoid** importing the `CoreModule` anywhere except in the `AppModule`.
-
-
-
-
-
-
-
-
-
-
-**Why?** A lazily loaded feature module that directly imports the `CoreModule` will make its own copy of services and likely have undesirable results.
-
-
-
-
-
-
-
-
-
-
-**Why?** An eagerly loaded feature module already has access to the `AppModule`'s injector, and thus the `CoreModule`'s services.
-
-
-
-
-
-
-
-
-
-
-**Do** export all symbols from the `CoreModule` that the `AppModule` will import and make available for other feature modules to use.
-
-
-
-
-
-
-
-
-
-
-**Why?** `CoreModule` exists to make commonly used singleton services available for use in the many other modules.
-
-
-
-
-
-
-
-
-**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.
-Yet there is a real danger of that happening accidentally if the `CoreModule` provides a service.
-
-
-
-
-
-
-
-
-
-
- src
-
-
-
-
-
- app
-
-
-
-
-
- core
-
-
-
-
-
- core.module.ts
-
-
-
- logger.service.ts|spec.ts
-
-
-
- nav
-
-
-
-
-
- nav.component.ts|html|css|spec.ts
-
-
-
-
-
- spinner
-
-
-
-
-
- spinner.component.ts|html|css|spec.ts
-
-
-
- spinner.service.ts|spec.ts
-
-
-
-
-
-
-
- app.component.ts|html|css|spec.ts
-
-
-
- app.module.ts
-
-
-
- app-routing.module.ts
-
-
-
-
-
- main.ts
-
-
-
- index.html
-
-
-
-
-
- ...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-`AppModule` is a little smaller because many app/root classes have moved to other modules.
-`AppModule` is stable because you will add future components and providers to other modules, not this one.
-`AppModule` delegates to imported modules rather than doing work.
-`AppModule` is focused on its main task, orchestrating the app as a whole.
-
+**Why?** The folder makes it easy to identify and isolate the feature content.
@@ -3202,124 +3121,25 @@ Yet there is a real danger of that happening accidentally if the `CoreModule` pr
{@a 04-12}
-### Prevent re-import of the core module
-
-#### Style 04-12
-
-Only the root `AppModule` should import the `CoreModule`.
-
-
-
-
-
-
-**Do** guard against reimporting of `CoreModule` and fail fast by adding guard logic.
-
-
-
-
-
-
-
-
-
-
-**Why?** Guards against reimporting of the `CoreModule`.
-
-
-
-
-
-
-
-
-
-
-**Why?** Guards against creating multiple instances of assets intended to be singletons.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Back to top
-
-{@a 04-13}
-
-### Lazy Loaded folders
-
-#### Style 04-13
-
-A distinct application feature or workflow may be *lazy loaded* or *loaded on demand* rather than when the application starts.
-
-
-
-
-
-
-**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.
-
-
-
-
-
-
-
-
-
-
-**Why?** The folder makes it easy to identify and isolate the feature content.
-
-
-
-
-
Back to top
-
-{@a 04-14}
-
### Never directly import lazy loaded folders
-#### Style 04-14
+#### Style 04-12
-
-
**Avoid** allowing modules in sibling and parent folders to directly import a module in a *lazy loaded feature*.
-
-
-
-
-
**Why?** Directly importing and using a module will load it immediately when the intention is to load it on demand.
-
Back to top
-
## Components
{@a 05-03}
@@ -3328,37 +3148,24 @@ A typical *lazy loaded folder* contains a *routing component*, its child compone
#### Style 05-03
-
-
**Consider** giving components an _element_ selector, as opposed to _attribute_ or _class_ selectors.
-
-
-
-
-
**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 web components.
-
-
-
-
-
**Why?** It is easier to recognize that a symbol is a component by looking at the template's html.
-
@@ -3371,16 +3178,10 @@ There are a few cases where you give a component an attribute, such as when you
-
-
-
-
-
-
@@ -3406,26 +3207,18 @@ There are a few cases where you give a component an attribute, such as when you
-
-
**Do** extract templates and styles into a separate file, when more than 3 lines.
-
-
-
**Do** name the template file `[component-name].component.html`, where [component-name] is the component name.
-
-
-
@@ -4073,7 +3866,7 @@ helps instantly identify which members of the component serve which purpose.
**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.
-If you use the `host` metadata property, you must modify both the property/method declaration in the
+If you use the `host` metadata property, you must modify both the property/method declaration in the
directive's class and the metadata in the decorator associated with the directive.
@@ -4271,7 +4064,7 @@ Compare with the less preferred `host` metadata alternative.
-
+
@@ -4515,8 +4308,6 @@ Useful tools and tips for Angular.
-
-
**Consider** using [snippets](https://marketplace.visualstudio.com/items?itemName=johnpapa.Angular2) for [Visual Studio Code](https://code.visualstudio.com/) that follow these styles and guidelines.