ホームページ - EY-Office

2023-08-01

TypeScript Style Guide、気になる点もあるが良さそうです

カテゴリー：React

ベテランのプログラマーは自分なりのコーディングスタイルやコードの美学を持っていると思いますが、まだ初心者の方やチームで開発する場合は基準になるコーディングスタイルガイドがると助かると思います。たとえばGoogle Style Guidesにはいくつかのプログラミング言語のスタイルガイドが書かれています。

少し前のReact NewsletterにTypeScript Style Guideの記事があったので、読んでみました。いかがなものか？と思う項目もありましたが、全体的には良いものだと思いました。とくにReactコンポーネントに付いて詳しく書かれているのでフロントエンドの開発者には有用だと思います。

TypeScript-Style-Guide DeepAIが生成した画像です

Introduction
Table of Contents
About Guide
TLDR
Data Immutability
Functions
Variables
Types
Naming
- Named Export
- Naming Conventions
- Comments
React Components
- Props
  - Using Props Type
  - Required & Optional Props
  - Using Discriminated Type
- Component Types
  - Container
  - UI - Feature
  - UI - Design system
- Passing Data
Source Organization
- Code Collocation
- Imports
- Project Structure
Tests - Unit & Integration
- What & How To Test
- Test Description
- Tooling Extension
- Snapshot

このスタイルガイドには、

Reactのコーディングに付いて詳しく書かれている
コーディングスタイル以外に以下が書かれている
- データの受け渡し（ステート管理）
- プロジェクトのディレクトリー構造
- テスト

雑な概要

全部を解説は出来ないですが、気になったところに付いて書いてみたいと思います。

Data Immutability

データはなるべくイミュータブルにしましょう！重要ですね。

Function

良いことがかかれています

関数はできるだけ、単一機能（単一責務）にする
関数はできるだけ、ステートレスにする
関数はできるだけ、1つ以上の引数を受け取り、値を戻すようにする
関数はできるだけ、副作用を持たないようにする
たくさんの引数を受け取るのは止め、オブジェクトで受け取るようにしよう
オプションの引数は少なめにしよう

Variables

定数代入を使おう const BASE_LOCATION = { x: 50, y: 130 } as const;
enum型には問題点が多いので、uniton型や定数のオブジェクト型を使おう
値が入ってない事を表すにはundefinedではなくnullを使おう、ただしフィールドの除外にはundefinedを使う

Type

interfaceではなくtypeを使おう
配列の型は string[]ではなく Array<string>を使おう
初期値等から型が明確になる場合は型を書かない
関数の戻り値は型推論されるが、明確に戻り値の型を書くことには数々のメリットがあるので書こう
型エラー抑制は@ts-ignoreではなく、説明付きの@ts-expect-errorを使おう
as 型 やbrand!.nameは危険なので使わないようにしよう
anyは危険なので使わないようにしよう、どうしても使いたい場合はunknownを使おう

Naming ルール

キャメルケースを使おう
論理値は is, has を付けよう
定数は全部大文字で書こう
ジェネリクスはTではなくTRequestのような内容を表す名前にしよう
…
コメントを書いて説明するのではなく、コメントが無くてもわかる名前を使う事が重要

React Components

Props

推奨スタイル

type FooProps = Readonly<{
  name: string;
  score: number;
}>;

export const Foo = ({ name, score }: FooProps) => {
  ...
}

名前はコンポーネント名Props
ほとんどのpropsは必須に、オプションpropsは控えめに
判別可能なユニオン型を使いオプションpropsを減らそう

Component Types

Container
- コンポーネント名はコンポーネント名Container または コンポーネント名Page
- ここには、ビジネスロジックやAPI呼び出しを含む
- …
UI - Feature (特定のUIコンポーネント、例. ProductItem)
- 極力、関数のルールに従う
- API呼び出し等はなし
- …
UI - Design system (汎用のUIコンポーネント、例. Button)
- …
Passing Data（ステート管理）
- Propsのたらい回し(Prop drilling)は問題ではない
- コンポーネントの合成は推奨されない *1
- サーバーステート・ライブラリを推奨 *2
- クライアントのステート管理ライブラリー非推奨 *2
  - どうしても使うならzustandがお勧め

*1 コンポーネントの合成は以下のようなコードです。

const Hello = () => <h1>Hello</h1>;
const App   = () => <div>{Hello()}</div>;  // ×

普通は以下のように書きますよね。

const Hello = () => <h1>Hello</h1>;
const App   = () => <div><Hello/></div>;  // ○

*2 私は、この主張には賛同できません。アプリの性格、使われる環境等に依存すると思います。
zustandは良いステート管理ライブラリーだと思います、以前ブログに書いています→React用ステート管理ライブラリーzustandは良さそうですね

Source Organization

原文を見てください

Tests - Unit & Integration

テストは重要です。初心者には難しかもしれませんが、テストは良いコードを書くための強力な武器になりますので、是非取得してください。

What & How To Test

すべきこと
- テストコードはシンプルで短く書く
- 意図が理解しやすテストを書く
- 使用方法に合わせたテストを書く
- 他のテストの実行順序に依存しないように書く
- 画面等の変更に強いテストを書く
すべきではないこと
- コードのリファクタリング時は、テストは変更しない
- 利用しているライブラリやフレームワークはテストしない
- 100%のコードカバレッジを求めない
- テストのためだけのテストは書かない