Skip to content

Latest commit

 

History

History
285 lines (173 loc) · 14.8 KB

STYLEGUIDE.md

File metadata and controls

285 lines (173 loc) · 14.8 KB
Raw

Angular Styleguide conformity

Angular Styleguide

This document tracks the conformity to the different rules of the Angular Styleguide.

Table of Contents

  1. 1. Single Responsibility
  2. 2. Naming
  3. Coding Conventions
  4. App Structure
  5. Components
  6. Directives
  7. Services
  8. Data Services
  9. Lifecycle Hooks
  10. Appendix

1. Single Responsibility

Rule of One STYLE 01-01

  • Do define one thing (e.g. service or component) per file.
  • Consider limiting files to 400 lines of code.

Small Functions STYLE 01-02

  • Do define small functions.
  • Consider limiting to no more than 75 lines.

2. Naming

General Naming Guidelines STYLE 02-01

  • Do use consistent names for all symbols.
  • Do follow a pattern that describes the symbol's feature then its type. The recommended pattern is feature.type.ts.

Separate File Names with Dots and Dashes STYLE 02-02

  • Do use dashes to separate words in the descriptive name.
  • Do use dots to separate the descriptive name from the type.
  • Do use consistent type names for all components following a pattern that describes the component's feature then its type. A recommended pattern is feature.type.ts.
  • Do use conventional type names including .service, .component, .pipe, .module, .directive. Invent additional type names if you must but take care not to create too many.

Symbols and File Names STYLE 02-03

  • Do use consistent names for all assets named after what they represent.
  • Do use upper camel case for class names. Match the name of the symbol to the name of the file.
  • Do append the symbol name with the conventional suffix for a thing of that type (e.g., Component, Directive, Module, Pipe, Service).
  • Do give the filename the conventional suffix for a file of that type (e.g., .component.ts, .directive.ts, .module.ts, .pipe.ts, .service.ts).

Service Names STYLE 02-04

  • Do use consistent names for all services named after their feature.
  • Do use upper camel case for services.
  • Do suffix services with Service when it is not clear what they are (e.g. when they are nouns).

Bootstrapping STYLE 02-05

  • 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 the main.ts. Instead consider placing it in a component or service.

3. Coding Conventions

Classes STYLE 03-01

  • Do use upper camel case when naming classes.

Constants STYLE 03-02

  • Do declare variables with const if their values should not change during the application lifetime.
  • Consider spelling const variables in lower camel case.
  • Do tolerate existing const variables that are spelled in UPPER_SNAKE_CASE.

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.

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.

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 assets alphabetically.

4. App Structure

LIFT STYLE 04-01

  • Do structure the app such that you can Locate code quickly, Identify the code at a glance, keep the Flattest structure you can, and Try to be DRY.
  • Do define the structure to follow these four basic guidelines, listed in order of importance.

Locate STYLE 04-02

  • Do make locating code intuitive, simple and fast.

Identify STYLE 04-03

  • Do name the file such that you instantly know what it contains and represents.
  • Do be descriptive with file names and keep the contents of the file to exactly one component.
  • Avoid files with multiple components, multiple services, or a mixture.

Flat STYLE 04-04

  • Do keep a flat folder structure as long as possible.
  • Consider creating sub-folders when a folder reaches seven or more files.
  • Consider configuring the IDE to hide distracting, irrelevant files such as generated .js and .js.map files.

T-DRY (Try to be DRY) STYLE 04-05

  • Do be DRY (Don't Repeat Yourself)
  • Avoid being so DRY that you sacrifice readability.

Overall Structural Guidelines STYLE 04-06

  • Do start small but keep in mind where the app is heading down the road.
  • Do have a near term view of implementation and a long term vision.
  • Do put all of the app's code in a folder named app.
  • Consider creating a folder for a component when is has multiple accompanying files (.ts, .html, .css and .spec).

Folders-by-Feature Structure STYLE 04-07

  • Do create folders named for the feature area they represent.
  • Do create an Angular module for each feature area.

App Root Module STYLE 04-08

  • Do create an Angular module in the app's root folder (e.g., in /app).
  • Consider naming the root module app.module.ts.

Feature Modules STYLE 04-09

  • Do create an Angular module for all distinct features in an application (e.g. Heroes feature).
  • Do place the feature module in the same named folder as the feature area (.e.g app/heroes).
  • 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 symbol reflecting the name of the feature area, folder, and file (e.g. app/heroes/heroes.module.ts defines HeroesModule)

Shared Feature Module STYLE 04-10

  • Do create a feature module named SharedModule in a shared folder (e.g. app/shared/shared.module.ts defines SharedModule).
  • Do put common components, directives and pipes that will be used throughout the application by other feature modules in the SharedModule, where those assets are expected to share a new instance of themselves (not singletons).
  • Do import all modules required by the assets in the SharedModule (e.g. CommonModule and FormsModule).
  • Do declare all components, directives, and pipes in the SharedModule.
  • Do export all symbols from the SharedModule that other feature modules need to use.
  • Avoid specifying app-wide singleton providers in a SharedModule. Intentional singletons are OK. Take care.

Core Feature Module STYLE 04-11

  • Do collect single-use classes and hiding their gory details inside CoreModule. A simplified root AppModule imports CoreModule in its capacity as orchestrator of the application as a whole.
  • Do create a feature module named CoreModule in a core folder (e.g. app/core/core.module.ts defines CoreModule).
  • Do put a singleton service whose instance wil 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).
  • 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).
  • Avoid importing the CoreModule anywhere except in the AppModule.
  • Do export all symbols that from the CoreModule that the AppModule will import and make available for other feature modules to use.

Prevent Reimport of Core Module STYLE 04-12

  • Do guard against reimporting of CoreModule and fail fast by adding guard logic.

Lazy Loaded Folders STYLE 04-13

  • 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.

Never Directly Import Lazy Loaded Folders STYLE 04-14

  • Avoid allowing modules in sibling and parent folders to directly import a module in a lazy loaded feature.

5. Components

Component Selector Naming STYLE 05-02

  • Do use dashed-case or kebab-case for naming the element selectors of components.

Components as Elements STYLE 05-03

  • Do define components as elements via the selector.

Extract Template and Styles to Their Own Files STYLE 05-04

  • 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.
  • Do name the style file [component-name].component.css, where [component-name] is the component name.

Decorate Input and Output Properties Inline STYLE 05-12

  • Do use @Input and @Output instead of the inputs and outputs properties of the @Directive and @Component decorators.
  • Do place the @Input() or @Output() on the same line as the property they decorate.

Avoid Renaming Inputs and Outputs STYLE 05-13

  • Avoid renaming inputs and outputs, when possible.

Member Sequence STYLE 05-14

  • Do place properties up top followed by methods.
  • Do place private members after public members, alphabetized.

Put Logic in Services STYLE 05-15

  • Do limit logic in a component to only that required for the view. All other logic should be delegated to services.
  • Do move reusable logic to services and keep components simple and focused on their intended purpose.

Don't Prefix Output Properties STYLE 05-16

  • Do name events without the prefix on.
  • Do name event handler methods with the prefix on followed by the event name.

Put Presentation Logic in the Component Class STYLE 05-17

  • Do put presentation logic in the component class, and not in the template.

6. Directives

Use Directives to Enhance an Existing Element STYLE 06-01

  • Do use attribute directives when you have presentation logic without a template.

Use HostListener and HostBinding Class Decorators STYLE 06-03

  • Consider preferring the @HostListener and @HostBinding to the host property of the @Directive and @Component decorators.
  • Do be consistent in your choice.

7. Services

Services are Singletons within an Injector STYLE 07-01

  • Do use services as singletons within the same injector. Use them for sharing data and functionality.

Single Responsibility STYLE 07-02

  • Do create services with a single responsibility that is encapsulated by its context.
  • Do create a new service once the service begins to exceed that singular purpose.

Providing a Service STYLE 07-03

  • Do provide services to the Angular injector at the top-most component where they will be shared.

Use the @Injectable() Class Decorator STYLE 07-04

  • Do use the @Injectable class decorator instead of the @Inject parameter decorator when using types as tokens for the dependencies of a service.

8. Data Services

Separate Data Calls STYLE 08-01

  • Do refactor logic for making data operations and interacting with data to a service.
  • Do make data services responsible for XHR calls, local storage, stashing in memory, or any other data operations.

9. Lifecycle Hooks

Implement Lifecycle Hooks Interfaces STYLE 09-01

  • Do implement the lifecycle hook interfaces.

10. Appendix

Codelyzer STYLE A-01

  • Do use codelyzer to follow this guide.
  • Consider adjusting the rules in codelyzer to suit your needs.

File Templates and Snippets STYLE A-02

  • Do use file templates or snippets to help follow consistent styles and patterns. Here are templates and/or snippets for some of the web development editors and IDEs.
  • Consider using snippets for Visual Studio Code that follow these styles and guidelines.
  • Consider using snippets for Atom that follow these styles and guidelines.
  • Consider using snippets for Sublime Text that follow these styles and guidelines.
  • Consider using snippets for Vim that follow these styles and guidelines.