TypeScript coding guidelines

TypeScript coding guidelines

The rules applied in the adidas JavaScript coding guidelines are also applied to TypeScript, so this document shows only the TypeScript specific rules.

See TypeScript specification in GitHub.

• Global Conventions
  • Types
  • Classes and interfaces
  • Namespaces and modules
  • Naming conventions
  • Documentation
• Linting tools
• Links of interest

Global Conventions

List of main rules, customized ones and examples.

Types

The data type is the most important feature which TypeScript provides, so, it is important to take advantage of it to write good TypeScript code. Primitive types, classes and interfaces can be used as a type of a variable/parameter.

The syntax is quite simple, just using : after the variable or parameter name followed by the type.

const description: Description = 'the type of the `description` variable is `Description`';

Rule	Reason
Type cast should be done with as syntax	Clarity, diamonds used for generics only
Do not set the type of initialized variables which type is inferred for its value	TypeScript rule
Do not set the type of parameters with a default value which type is inferred for its value	TypeScript rule
Do not use any, use a new type to be assigned to the value	Coherence
Use type over interface for new types	Coherence, use interface for inheritance only

// new type declaration
type Description = {
    description: string;
    length: number;
};

// variable declaration
const description: Description = {
  description: 'the type of the `description` variable is `Description`',
  length: 55
};
const language = new Language('typescript');
const stringVariable = 'string type';

// parameter
function doSomething(description: Description = { description: 'description', length: 11 }) {}
function doSomething(description: Description) {}
function doSomething(stringVariable = 'string type') {}

Classes and interfaces

The classes and interfaces are not mandatory to be used, they are more related to Object-oriented programming. The recommendation is to use:

• Classes: for OO programming if it is necessary to create instances.
• Interfaces: to be able to inherit using the same interface (implements).
• Types: for new types, an interface can be a type, and an interface or a type can be composed by different types.

class Description {
  private length: number;
  
  constructor(private description = '') {
    this.length = description.length;
  }
  
  truncate(size: number) {
    return this.description.slice(0, size);
  }
}

// interface
interface Description {
    description: string;
    length: number;
    truncate(size: number): {}
}

Namespaces and modules

Namespaces and modules are not allowed as part of the codebase.

Naming conventions

Most of the JavaScript naming rules are applied, however in TypeScript we can, optionally, use these specific rules.

Rule	Reason
The interfaces can start with I	Distinguish interfaces from classes
The interface filenames end with .i before its extension	Distinguish interface files from other ones
The classes and interface files are capitalized	Distinguish classes and interface from other files

Documentation

The main difference between JavaScript documentation rules and the TypeScript ones is that the type of the parameters and returned value is inherited from the function definition. So, it is important to set the types.

/**
 * Start the selected task.
 * @param task - Task to be executed.
 * @returns Promise with the status of the task.
 */
function start(task: Task): Promise<boolean> {}

The JavaScript documentation is based on @use JSDoc format.

Rule	Reason
Do not set the type of the parameters and returned value in the function documentation	TypeScript general rule

Linting tools

The linter configuration is based on ESLint and it is available in the repository js-linter-configs.

It can be used as NPM package: eslint-config-adidas-typescript.

Links of interest

• TypeScript Homepage
• TypeScript specification
• ESLint Homepage [ESLint]
• JSDoc