TypeScript Maintainability Standards · TS-02

A TypeScript reflection of CS-01.1

Methods that require more than 10 statements are doing too much, engineers must make conscious, critical analysis of their work and provide methods with clear names.

If the same statement, or statement group, appears multiple times in the codebase. Then, the responsibility of this logic should belong to one abstraction which is used in both places.

This rule enforces the DRY principle

Methods which contain control statements (such as if, while, for) must only have up to 2 of such statements nested before abstracting the nested control statements into private methods.

Excessive nesting results in unmaintainable code which takes time to understand. Engineers must abstract each stage of the nested statements into a understandable methods.

A TypeScript reflection of CS-01.21

Reduce method complexity by ensuring methods do not have more than 4 parameters. Use objects or data structures to encapsulate multiple parameters if necessary.

Magic numbers and strings present maintainability issues and must be avoided at all times.

When a fixed set of constants is used for logic, these should be grouped into an Enum. This aides readibilty by giving names and groupings to magic numbers and strings.

A TypeScript reflection of CS-01.27

Allow future extensions or specific business requirements by leaving gaps between the numeric values of an enum, e.g. [0, 100, 200].

A TypeScript reflection of CS-01.26

To maintain cleanliness, any code that the compiler cannot reach should never be checked-in.

Never use ”*” or ”^” for the target version of an imported package. This kind of usage can result in unexpected behaviour or the unintentional introduction of breaking changes.

Integrate a logging tool to track and diagnose runtime errors in development and production. This can be achieved with an error handling middleware.

Error logging tool such as Sentry or Winston can be implemented to capture errors on the front end.

A TypeScript reflection of CS-01.6

Type null safety should be enforced on TS projects, making full use of TypeScript’s benefits that reduce runtime errors and aide readibility. Engineers should be made to explciity state if a value might be null or undefined.

Optimising imports is important for the scalability of an application. As applications grow and file paths become longer as a result, it’s important that we keep these maintainable and readable.

Use relative imports · TS-02.14 · SHOULD

Dependency management and module portability should be optimised through the use of relative paths.

Relative import example (✅)

import { MyComponent } from './components/MyComponent';
import { Utils } from '../utils/Utils';

Absolute import example (❌)

import { MyComponent } from 'project-name/src/components/MyComponent';
import { Utils } from 'project-name/src/utils/Utils';

Configure aliases for improved readability · TS-02.15 · SHOULD

Aliases can be configured in tsconfig.json or in webpack to optimise imports into groups.

tsconfig.json alias example (✅)

  "compilerOptions": {
    "paths": {
      "@components/*": ["src/components/*"],
    }
  }

Usage

import { MyComponent } from '@components/MyComponent';