Lab Style Guide: TypeScript

TypeScript Style Guide

For readability and maintainability, it’s critical to use a consistent coding style. The coding rules described in this document will help ensure that consistency.

Organization

Organize your computer code like you would a scientific paper.

The largest unit of organization in a paper is the section (e.g., the “Results” section, the “Discussion” section, etc.).

In code, a “section” is comprised of all program elements that share the same general purpose (e.g., string manipulation, user input, etc.).

Each code section should be saved in a separate file. Organize your files in subdirectories to reflect the hierarchical organization of your code. In TypeScript, that means saving ts files to subdirectories and including them in your main script like this: /// <reference path='path/to/my_typescript.ts' />

In a scientific paper, sections are divided into subsections.

In code, each class or function in a given file is equivalent to a subsection.

Typically there will be one class in each file, though in some cases multiple classes/functions per file may be appropriate.

In scientific writing, subsections are divided into paragraphs.

In code, each of the functions within a class are like a paragraph.

Like a paragraph, the code in each function should be focused on a single task (like a topic sentence).

Paragraphs are made of sentences.

In code, a “sentence” is a few commands that perform the same subtask.

It’s not necessary to comment every line, but it is best to include a brief comment at the beginning of each code “sentence.”