StyleGuide

Неофіційний посібник зі стилю TypeScript

Люди запитували мене про мою думку щодо цього. Особисто я не дуже наполягаю на дотриманні цього в своїх командах і проектах, але це допомагає згадувати про це як тай-брейк, коли хтось відчуває потребу мати таку послідовність. Є інші речі, щодо яких я відчуваю набагато більше, і вони описані в розділі про поради (наприклад, твердження типу погане, налаштування властивостей погане) 🌹.

Ключові розділи:

• Variable

• Class

• Interface

• Type

• Namespace

• Enum

• null vs. undefined

• Formatting

• Single vs. Double Quotes

• Tabs vs. Spaces

• Use semicolons

• Annotate Arrays as Type[]

• File Names

• type vs interface

• == or ===

Variable and Function

• Використовуйте camelCase для імен змінних і функцій

Причина: звичайний JavaScript

Bad

var FooVar;
function BarFunc() { }

Good

var fooVar;
function barFunc() { }

Class

• Використовуйте PascalCase для імен класів.

Причина: це насправді досить традиційно для стандартного JavaScript.

Bad

class foo { }

Good

class Foo { }

• Використовуйте camelCase членів класу та методів

Причина: природно випливає з умов іменування змінних і функцій.

Bad

class Foo {
    Bar: number;
    Baz() { }
}

Good

class Foo {
    bar: number;
    baz() { }
}

Interface

• Використовуйте PascalCase для імені.

Причина: Подібно до класу

• Використовуйте camelCase для членів.

Причина: Подібно до класу

• Не вживайте префікс I

Причина: нетрадиційне. lib.d.ts визначає важливі інтерфейси без I (наприклад, Window, Document тощо).

Bad

interface IFoo {
}

Good

interface Foo {
}

Type

• Використовуйте PascalCase для імені.

Причина: Подібно до класу

• Використовуйте camelCase для учасників.

Причина: Подібно до класу

Namespace

• Використовуйте PascalCase для імен

Причина: Конвенція, яку дотримується команда TypeScript. Простори імен фактично є просто класом зі статичними членами. Імена класів: PascalCase => Імена простору імен: PascalCase

Bad

namespace foo {
}

Good

namespace Foo {
}

Enum

• Використовуйте PascalCase для імен enum

Причина: Подібно до класу. Є типом.

Bad

enum color {
}

Good

enum Color {
}

• Використовуйте PascalCase для члена enum

Причина: Конвенція, якої дотримується команда TypeScript, тобто розробники мови, наприклад SyntaxKind.StringLiteral. Також допомагає з перекладом (генерацією коду) інших мов на TypeScript.

Bad

enum Color {
    red
}

Good

enum Color {
    Red
}

Null vs. Undefined

• Бажано не використовувати жоден із них у разі явної недоступності

Причина: ці значення зазвичай використовуються для підтримки узгодженої структури між значеннями. У TypeScript ви використовуєте types для позначення структури

Bad

let foo = { x: 123, y: undefined };

Good

let foo: { x: number, y?: number } = { x:123 };

• Загалом використовуйте undefined (замість цього подумайте про повернення об’єкта на зразок {valid:boolean, value?:Foo})

Bad

return null;

Good

return undefined;

• Використовуйте null, якщо це частина API або домовленість

Причина: це традиційно в Node.js, напр. error має значення null для зворотних викликів у стилі NodeBack.

Bad

cb(undefined)

Good

cb(null)

• Використовуйте правдиву перевірку для того, для об’єктів null or undefined

Bad

if (error === null)

Good

if (error)

• Використовуйте == null / != null (а не === / !==), щоб перевірити наявність null / undefined на примітивах, оскільки це працює як для null/undefined, але не інші помилкові значення (наприклад, '', 0, false), напр.

Bad

if (error !== null) // does not rule out undefined

Good

if (error != null) // rules out both null and undefined

Formatting

Компілятор TypeScript постачається з дуже гарною мовною службою форматування. Незалежно від результату, який він дає за замовчуванням, достатньо, щоб зменшити когнітивне перевантаження команди.

Використовуйте tsfmt, щоб автоматично форматувати свій код у командному рядку. Крім того, ваша IDE (atom/vscode/vs/sublime) уже має вбудовану підтримку форматування.

приклади:

// Space before type i.e. foo:<space>string
const foo: string = "hello";

Quotes

• Надавати перевагу одинарним лапкам ('), якщо не використовувати екранування.

Причина: це робить більше команд JavaScript (наприклад, airbnb, стандарт, [npm](https: //github.com/npm/npm), вузол, google/angular, facebook /react). Це легше друкувати (на більшості клавіатур не потрібен зсув). Команда Prettier також рекомендує одинарні лапки

Подвійні лапки не без переваг: дозволяють легше копіювати вставляти об’єкти в JSON. Дозволяє людям використовувати інші мови для роботи без зміни символу цитати. Дозволяє використовувати апостроф, напр. He's not going.. Але я не хочу відхилятися від того, що спільнота JS вирішила справедливо.

• Якщо ви не можете використовувати подвійні лапки, спробуйте використовувати зворотні галочки (`).

Причина: вони зазвичай представляють намір досить складних рядків.

Spaces

• Використовуйте два пробіли, не табуляцію.

Причина: це робить більше команд JavaScript (наприклад, airbnb, idiomatic, standard, npm, вузол, google/ angular, facebook/react). Команди TypeScript/VSCode використовують 4 пробіли, але, безперечно, є винятком у екосистемі.

Semicolons

• Використовуйте крапку з комою.

Причини: явні крапки з комою допомагають інструментам форматування мови давати послідовні результати. Відсутній ASI (автоматична вставка крапки з комою) може призвести до помилок, напр. foo() \n (function(){}) буде одним оператором (а не двома). TC39 попередження про це також. Приклади команд: airbnb, idiomatic, [google/angular](https://github .com/angular/angular/), facebook/react, Microsoft/TypeScript.

Array

• Анотуйте масиви як foos: Foo[] замість foos: Array<Foo>.

Причини: легше читати. Він використовується командою TypeScript. Полегшує пізнання того, що щось є масивом, оскільки розум навчений виявляти [].

Filename

Назвіть файли за допомогою camelCase. наприклад utils.ts, map.ts тощо.

Причина: традиційно для багатьох команд JS.

Коли файл експортує компонент, а ваша структура (як-от React) хоче, щоб компонент був застосований до PascalCased, використовуйте назву файлу регістра pascal, щоб відповідати, наприклад, Accordion.tsx, MyControl.tsx.

Причина: допомагає забезпечити послідовність і те, що робить екосистема.

type vs. interface

• Використовуйте type, коли вам може знадобитися об'єднання або intersection:

type Foo = number | { someProperty: number }

* Використовуйте `interface`, коли ви хочете `extends` або `implements`, напр.

interface Foo { foo: string; } interface FooBar extends Foo { bar: string; } class X implements FooBar { foo: string; bar: string; }

* В іншому випадку використовуйте те, що робить вас щасливими в цей день. Я використовую [type](https://www.youtube.com/watch?v=IXAT3If0pGI)

## `==` або `===`
Обидва [здебільшого безпечні для користувачів TypeScript](https://www.youtube.com/watch?v=vBhRXMDlA18). Я використовую `===`, оскільки це те, що використовується в кодовій базі TypeScript.