Coding Guidelines

Dex Frontend Coding guidelines

The following guide describes the code styles and guidelines used for the frontend of Dex which is built with Angular.

💡 Tips about the Angular CLI

When using the Angular CLI every command can be shorted down to a single letter. This is possible since the Angular CLI knows no commands with the same first letter. The following two examples of commands execute the same.

ng generate component modules/biometric/components/heart-rate
ng g c modules/biometric/components/heart-rate

ng serve -o
ng s -o

Besides that when generating components, modules, service or other Angular components it is recommend to add the flag --skipTests to your command in order to avoid the CLI to generate test files which are not used within this project.

🧱 Project Structure

Components

• Non feature components should be in the folder app/components
• Feature components should be in the folder components of the feature module app/modules/MODULE_NAME/components

Modules

Every module should be located in the folder app/modules.

Services

Every service should be located in the folder app/services.

🏷️ Naming

Components

When creating components do not include the word component in name because the Angular already takes care of adding the name component. Every component should belong to a module and be in the sub folder called components in the folder of the module. The naming rule used for components is kebab-case. For example:

Do ✔️

/modules/biometric/components/active-minutes.component.ts

Don't ❌

/modules/biometric/Active_Minutes.component.ts

This component can be created with the following CLI command:

ng g c modules/biometric/components/active-minutes --skipTests

Services

Services follow the same rules as components. With the only difference being that the services should be in the folder named services.

/services/user.services.component.ts

This service can be created with the following CLI command:

ng g s services/user --skipTests

Modules

Modules follow the same rules as components. With the only difference being that the services should be in the folder named modules. When routing for the module is needed the flag --routing should be added.

/modules/dashboard-overview/dashboard-overview.module/ts

This module can be created with the following CLI command:

ng g m modules/dashboard-overview --skipTests --routing

CSS

For naming of (S)CSS classes and ids use kebab-case.

Do ✔️

.navigation-title-container

Don't ❌

.goback_button

As a general guideline, BEM should be followed. In short, this means that when naming 'elements', referring to HTML elements that are part of a larger component named a 'block' (e.g. list items in a list), the class name should be prepended with two underscores plus the element name.

.project-tags {
  &__tag { } // Produces .project-tags__tag as class name
}

In addition to this, element modifiers should be named similarly using two dashes instead of underscores, indicating that the class is used to modify the looks of an element or block.

.button {
  &--size-large { } // Produces .button--size-large as class name
}

Typescript

For naming of typescript variables and methods use pascalCase. Methods which are triggered by changes such as clicking a button or changing a selector should be start with on, such as onClickBackButton andonUserSelectChange().

Do ✔️

onClickBackToOverview()
convertBiometricLogToGraphData()

Don't ❌

BacktoOverview()
Retrieve_UserData()

📦 Methods and variables order

When using typescript files use the following order:

1. ViewChild refs (for instance a ViewChild to an Angular Material component)
2. public variables
3. private variables
4. constructor
5. Angular life cycle hooks (such as ngOnInit & ngOnChanges)
6. public methods
7. private methods

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  @ViewChild('matSelect') themeSelect: MatSelect;

  public displayNavBar: boolean;

  private selectedTheme = 1;

  constructor() {

  }

  ngOnInit() {

  }

  public onThemeSelectChange(): void {

  }

  private fetchTheme(themeId: number): any {

  }
}

🧭 Type definition

Type definition should always be applied to methods and variables. In cases where the type is unclear use any.

Methods

Methods should be annotated with their type.

Do ✔️

public onThemeSelectChange(): void {}
private retrieveUsers(): User[] {}

Don't ❌

public onThemeSelectChange() {}
private retrieveUsers() {}

Variables

Variables should be annotated with their type useless the type can be inferred from initialization.

Do ✔️

public navBarOpen: boolean;
private defaultSelectedTabIndex = 1;

Don't ❌

public navBarOpen;
private defaultSelectedTabIndex: number = 1;

🔒 Access modifiers

Methods and variables should be annotated with a access modifiers. Within this project public and private are the only used access modifiers.

• public is used when template access is necessary.
• private is used when it is not needed in the template

📗 Documentation

Typescript

Variables and methods are documented with the use of JSDoc. The only exempts are made for the constructor and ng life cycle hooks. There is built in support for JSDoc in Visual Studio Code. Use the following syntax in the line above the method or variable you want to document.

/**
private fetchTheme(themeId: number): any {

Code completion should now appear, press enter.

From this point you can add your documentation.

  /**
   * 
   * @param themeId 
   */
  private fetchTheme(themeId: number): any {

  }

Final result.

  /**
   * Method to fetch a theme based on the id.
   * @param themeId id of the theme to fetch.
   */
  private fetchTheme(themeId: number): any {

  }

(S)CSS

(S)CSS should only be documented when complex (S)CSS is used. For example to create animations.

HTML

No documentation is used in HTML files.