TypeScript Style Guide

This article specifies the most general guidelines used for all Spire projects written using TypeScript as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern web development practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

Development Environment

The primary operating systems supported by Spire projects are Ubuntu 18.02 LTS, Windows 10, and macOS. On all systems, nodejs is used as the build system and webpack is used as the bundler.

For source control, git is used and projects are to be hosted on Spire Trading's Github page.

Each developer is welcome to use an editor of their choice, however Visual Studio Code is recommended.

File Names

Use snake case using all lower case letters for files and directories. The name of a file should correspond to the primary class that it exports.

The default extension for TypeScript files is ts

The extension used for TypeScript files containing JSX is tsx

All files end with a single new line character.

Directory Structure

A project is broken down into a library component, a test component, and one or more application components. These components are referred to as artifacts. The applications go into their own applications directory and the libraries into the library directory. Within each artifact is a build directory containing the build scripts needed to build that artifact. Scripts for POSIX systems are found in the posix sub-directory and Windows build files are within the windows sub-directory. The build scripts specified are setup to download and install any dependencies needed to produce the artifact and the build script which produces the artifact. Typically the setup script is run only once or when a new dependency is introduced to the project, and the build script is run anytime a new build is needed.

Finally there is a top-level build directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a setup script which downloads all third party dependencies. Some projects may also opt to include an install script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named sudoku the following directory structure should be used: