Skip to content

Latest commit

 

History

History
72 lines (51 loc) · 2.85 KB

STYLE.md

File metadata and controls

72 lines (51 loc) · 2.85 KB

Introduction

This file describes the various style and design conventions that are used in the Kent dashboard repository.

TypeScript Coding Conventions

Our TypeScript style is inspired by the style guidelines of the TypeScript implementation itself.

Naming

  1. Use PascalCase for type names.
  2. Do not use I as a prefix for interface names.
  3. Use PascalCase for enum values.
  4. Use camelCase for function names.
  5. Use camelCase for property names and local variables.
  6. Use _ as a prefix for private properties.
  7. Use whole words in names when possible.
  8. Give type parameters names prefixed with T, for example Request<TBody>.

Syntax and Types

  1. Use undefined. Do not use null.
  2. Prefer for..of over .forEach.
  3. Do not introduce new types/values to the global namespace.

File and Export Structure

  1. Keep main.ts free from implementation, it should only contain re-exports.
  2. If a file has a single or a main export, name the file after the export.

Documentation Guidelines

We use API Extractor to generate our documentation, which in turn uses TSDoc to parse our doc comments.

The doc comments are of the good old /** ... */ format, with tags of the format @<tag> used to mark various things. The TSDoc website has a good index of all available tags.

There are a few things to pay attention to, in order to make the documentation show up in a nice way on the website...

Use @remarks to split long descriptions

The API reference has an index of exported symbols for each package, which uses a short description, while clicking through to the page for a symbol shows the full description. By default all descriptions are considered "short", and you have to manually add a divider where the description should be cut off using the @remarks tag.

/**
 * This function helps you create a thing.
 *
 * @remarks
 *
 * Here is a much longer and more elaborate description of how the
 * creation of a thing works, which is way too long to fit on the index page.
 */
function createTheThing() {}

Use @param to document parameters

When using the @param tag to document a parameter it will show up in the Parameters section:

image

Be sure to include a - after the parameter name as well as required by TSDoc, or you'll get a warning in the API report.

/**
 * Generates a PluginCacheManager for consumption by plugins.
 *
 * @param pluginId - The plugin that the cache manager should be created for. Plugin names should be unique.
 */
forPlugin(pluginId: string): PluginCacheManager {
  ...
}