コードに意味を与える技術

状態管理が語るアプリケーションの意図 - データの流れと変化を明確にする技術

Tags: 状態管理, 設計, 可読性, 保守性, リファクタリング, アーキテクチャ, JavaScript, TypeScript

はじめに

アプリケーション開発において、データの「状態」は常に変化します。ユーザーの操作、サーバーからの応答、タイマーイベントなど、様々な要因によってアプリケーションの状態は移り変わります。この状態を管理することは、特にモダンなWebアプリケーション開発においては避けて通れない課題です。

しかし、状態管理のコードは往々にして複雑になりがちです。状態の定義、変化のトリガー、変化に伴う副作用などがコードの様々な場所に散らばり、「このデータはどこから来て、なぜこのように変わるのか」「この状態の変化はアプリケーションの他の部分にどのような影響を与えるのか」といった開発者の意図が読み取りにくくなってしまうことがあります。

これは、コードの可読性や保守性を著しく損なうだけでなく、チームでのコードレビューにおける指摘の増加や、他者コードの理解を困難にする要因となります。本稿では、プログラマーがコードを通じて状態管理の意図を効果的に伝えるための技術と考察をご紹介します。

状態管理における「意図」とは何か

状態管理における「意図」とは、単に現在のデータの値を保持することだけではありません。それは以下の要素を含む、アプリケーションの振る舞いの核となる情報です。

これらの「意図」がコードから明確に読み取れるかどうかが、状態管理コードの品質を大きく左右します。

意図を不明瞭にする状態管理のアンチパターン

状態管理において、開発者の意図が失われやすい典型的なアンチパターンをいくつか見てみましょう。

アンチパターン例1：グローバル変数やオブジェクトプロパティへの直接的な状態変更

アプリケーション全体からアクセス可能な場所に状態を置き、その状態を直接的に書き換える方法です。一見シンプルですが、状態がどこで、なぜ、どのように変化したのかを追跡することが非常に困難になります。

// Before: どこからでも状態を変更できる（意図が不明瞭）

// グローバル変数や容易にアクセス可能なオブジェクト
const appState = {
  isLoading: false,
  userData: null,
  error: null
};

function fetchData(userId) {
  appState.isLoading = true; // どこでisLoadingがtrueになったか追跡しにくい
  fetch(`/api/users/${userId}`)
    .then(response => response.json())
    .then(data => {
      appState.userData = data; // どこでuserDataがセットされたか追跡しにくい
      appState.isLoading = false;
    })
    .catch(err => {
      appState.error = err; // どこでerrorがセットされたか追跡しにくい
      appState.isLoading = false;
    });
}

// アプリケーションの別の場所
function processUserData() {
  if (appState.userData) {
    // userDataがどのように、いつセットされたか分かりにくい
    console.log(appState.userData.name);
  }
}

// 更に別の場所
function displayLoadingStatus() {
  // isLoadingがどのように、いつ変更されたか分かりにくい
  if (appState.isLoading) {
    console.log('Loading...');
  }
}

このコードでは、appStateという状態が様々な関数によって直接変更されています。isLoadingがtrueになるのはfetchData関数の開始時であるという意図は、この例ではまだ読み取れますが、コードベースが大きくなると、状態の各プロパティが「いつ」「なぜ」特定の値をを持つのかを理解するのが極めて難しくなります。

アンチパターン例2：マジックストリングや曖昧なデータ構造による状態定義

状態の値や構造がマジックストリング（コード中に直接書き込まれた意味不明な文字列）であったり、意図が伝わらないジェネリックなデータ構造であったりする場合も、コードの意図は不明瞭になります。

// Before: 状態の値や構造の意図が不明瞭

const order = {
  status: 'processing', // 'processing', 'shipped', 'delivered' などのマジックストリング？
  items: [ // itemsの各要素の構造は？
    { id: 1, name: 'Book', price: 2000, quantity: 1 },
    { id: 2, name: 'Pen', price: 100, quantity: 5 }
  ],
  shippingInfo: { // shippingInfoのプロパティの意味は？
    addr: 'Tokyo',
    receiver: 'Taro',
    method: 'express' // 'express', 'standard' などのマジックストリング？
  }
};

// status === 'processing' の意味するところは何？
if (order.status === 'processing') {
  // ...
}

// method === 'express' の意味する配送方法は？
if (order.shippingInfo.method === 'express') {
  // ...
}

状態の取りうる値が明示されていなかったり、データ構造の各フィールドが何を表すのかが不明瞭だったりすると、その状態を利用する側は推測に頼るしかなくなり、バグの原因となります。

コードで状態管理の意図を明確にする具体的な手法

これらのアンチパターンを避け、状態管理の意図をコードで明確に伝えるための具体的な手法を見ていきましょう。

1. 状態そのものの定義を明確にする

状態がどのような要素から成り立ち、それぞれの要素がどのような意味を持つのかをコード上で明確に表現します。TypeScriptの型定義、Enum、クラスなどを活用できます。

// After: TypeScriptの型定義とEnumで状態の意図を明確に

enum OrderStatus {
  Processing = 'processing',
  Shipped = 'shipped',
  Delivered = 'delivered',
  Cancelled = 'cancelled'
}

enum ShippingMethod {
  Standard = 'standard',
  Express = 'express'
}

interface OrderItem {
  id: number;
  name: string;
  price: number;
  quantity: number;
}

interface ShippingInfo {
  address: string; // addr -> address などより明確な命名に
  receiverName: string; // receiver -> receiverName
  method: ShippingMethod; // マジックストリングをEnumに
}

interface Order {
  id: number;
  status: OrderStatus; // マジックストリングをEnumに
  items: OrderItem[]; // 要素の型を定義
  shippingInfo: ShippingInfo; // ネストしたオブジェクトの型を定義
}

const order: Order = {
  id: 123,
  status: OrderStatus.Processing, // Enumを使用し、取りうる値を制限・明確化
  items: [
    { id: 1, name: 'Book', price: 2000, quantity: 1 },
    { id: 2, name: 'Pen', price: 100, quantity: 5 }
  ],
  shippingInfo: {
    address: 'Tokyo',
    receiverName: 'Taro',
    method: ShippingMethod.Express // Enumを使用し、取りうる値を制限・明確化
  }
};

// Enumを使用することで、状態が取りうる値の意図が明確になる
if (order.status === OrderStatus.Processing) {
  // ...
}

型定義やEnumを使用することで、状態の構造や各プロパティ・値が持つ意味、そして取りうる値の範囲がコードそのものから読み取れるようになります。これにより、誤った値の設定を防ぎ、状態を利用する側の理解も深まります。

2. 状態変更ロジックを集約し、意図を込めた命名を行う

状態を変更する処理は、可能な限り特定の関数やメソッド内に集約し、その関数名やメソッド名で「どのような目的で状態を変更するのか」という意図を明確に伝えます。

// After: 状態変更ロジックを関数に集約し、意図を込めた命名を行う

interface UserState {
  isLoading: boolean;
  userData: any | null; // 適切な型に置き換えるべき
  error: Error | null;
}

const userState: UserState = {
  isLoading: false,
  userData: null,
  error: null
};

// 状態変更の意図が明確な関数名
function startLoadingUser() {
  userState.isLoading = true;
  userState.error = null; // Loading開始時はエラーをクリアするという意図
}

function finishLoadingUser(data: any) { // ユーザーデータ取得成功の意図
  userState.userData = data;
  userState.isLoading = false;
}

function failLoadingUser(err: Error) { // ユーザーデータ取得失敗の意図
  userState.error = err;
  userState.isLoading = false;
}

// 外部から呼び出す処理
function fetchData(userId: number) {
  startLoadingUser(); // ロード開始の意図が明確
  fetch(`/api/users/${userId}`)
    .then(response => response.json())
    .then(data => {
      finishLoadingUser(data); // 成功時の状態更新の意図が明確
    })
    .catch(err => {
      failLoadingUser(err); // 失敗時の状態更新の意図が明確
    });
}

// 状態を利用する側も、状態変更がどのように行われるかの意図を理解しやすい
// function processUserData() { if (userState.userData) { ... } }
// function displayLoadingStatus() { if (userState.isLoading) { ... } }

状態変更の処理を関数としてカプセル化し、その関数名に「ユーザーデータのロードを開始する」「ユーザーデータのロードを完了する」「ユーザーデータのロードに失敗する」といった具体的な意図を含めることで、コードを読むだけで状態がどのように遷移するのかを理解しやすくなります。また、どの関数を呼び出せばどのような状態変化が起こるのかが明確になります。

3. データの流れと依存関係を表現する

データがアプリケーション内をどのように流れ、ある状態の変化が他の状態や表示にどのように影響するのかをコードの構造やパターンで表現します。FluxやReduxのような状態管理パターンは、このデータの流れを一方向にすることで意図を明確にしようとします。特定のライブラリを使わない場合でも、イベント発行/購読パターンや、状態を持つオブジェクトとそれを利用するオブジェクトの関係性を整理することで、データの依存関係を明確にできます。

// Before: データの流れと依存関係がコード上で分かりにくい

class Cart {
  items: any[] = [];
  addItem(item: any) { this.items.push(item); }
  removeItem(itemId: number) { /* ... */ }
  getTotalPrice() { /* ... */ return 0; }
}

class Display {
  updateCartDisplay(cartItems: any[]) { /* DOM操作 */ }
  updateTotalPriceDisplay(total: number) { /* DOM操作 */ }
}

const cart = new Cart();
const display = new Display();

// UIイベントハンドラ
document.getElementById('add-button').addEventListener('click', () => {
  const newItem = { id: 3, name: 'Eraser', price: 50 }; // 新しいアイテムを作成
  cart.addItem(newItem); // カートの状態を変更
  display.updateCartDisplay(cart.items); // 状態変更を受けて表示を更新
  display.updateTotalPriceDisplay(cart.getTotalPrice()); // 別の表示も更新
  // この処理がどこで行われているか、他の部分への影響は何かを追跡するのが難しい
});

// After: データの流れ（カートの状態変更 -> 通知 -> 表示更新）をイベントで表現

// EventEmitterのような概念（ここではシンプルな実装例）
class EventEmitter {
  private listeners: { [event: string]: Function[] } = {};
  on(event: string, listener: Function) {
    if (!this.listeners[event]) {
      this.listeners[event] = [];
    }
    this.listeners[event].push(listener);
  }
  emit(event: string, ...args: any[]) {
    if (this.listeners[event]) {
      this.listeners[event].forEach(listener => listener(...args));
    }
  }
}

class CartStore extends EventEmitter { // 状態を持つStoreがEventEmitterを継承
  private _items: any[] = []; // 内部状態はプライベートに

  get items() { return this._items; }

  addItem(item: any) {
    // 状態変更ロジックをカプセル化
    this._items.push(item);
    // 状態が変更されたことを通知（意図：カートにアイテムが追加された）
    this.emit('itemsChanged', this._items);
  }

  removeItem(itemId: number) {
    this._items = this._items.filter(item => item.id !== itemId);
    // 状態変更されたことを通知（意図：カートからアイテムが削除された）
    this.emit('itemsChanged', this._items);
  }

  getTotalPrice() {
    return this._items.reduce((total, item) => total + item.price * item.quantity, 0);
  }
}

// UI（Displayオブジェクトを模倣）はStoreの変更通知を購読
const cartStore = new CartStore();
const cartDisplay = document.getElementById('cart-display');
const totalPriceDisplay = document.getElementById('total-price-display');

// 意図：カートアイテムリストの表示を更新する
cartStore.on('itemsChanged', (items: any[]) => {
  // 状態変更イベントを受けて表示を更新するロジック
  if (cartDisplay) {
    cartDisplay.innerHTML = items.map(item => `<li>${item.name} x ${item.quantity}</li>`).join('');
  }
  // 意図：合計金額の表示を更新する
  if (totalPriceDisplay) {
    totalPriceDisplay.textContent = `Total: ${cartStore.getTotalPrice()} JPY`;
  }
});

// UIイベントハンドラはStoreの状態変更メソッドを呼び出すだけ
document.getElementById('add-button').addEventListener('click', () => {
  const newItem = { id: 3, name: 'Eraser', price: 50, quantity: 1 };
  cartStore.addItem(newItem); // 意図：新しいアイテムをカートに追加する
  // 表示更新ロジックはEventEmitter内で処理される
});

このAfterの例では、CartStoreが状態を管理し、状態が変更されたときにitemsChangedイベントを発行します。UIコンポーネント（ここでは単純化された表示更新ロジック）は、このイベントを購読し、通知を受け取った際に自身の表示を更新します。これにより、「UI操作 -> Storeの状態変更メソッド呼び出し -> Storeからイベント発行 -> UIがイベントを購読し表示更新」という明確なデータの流れがコード上で表現されます。状態変更ロジック（addItemなど）と、その変更を受けて何が起こるか（表示更新など）の間の依存関係がイベント通知という形で明確になります。

4. 副作用を分離する

API呼び出しやローカルストレージへの書き込みなど、状態変更に伴う副作用は、状態変更ロジックそのものから分離することで、状態変更の意図をより明確に保つことができます。前述のfetchDataの例では、データ取得という副作用と状態更新が同じ関数内に混在していました。これを分離することで、状態変更関数の役割は「状態を更新すること」に限定され、副作用の役割は「外部とのやり取りを行うこと」に限定されます。

この概念は、Redux-SagaやRedux-Thunk、Vuex Actionsなど、多くの状態管理ライブラリで「Effect」や「Action」といった形で提供されています。副作用を扱うレイヤーと、純粋な状態変更ロジック（Reducerなど）を分けることで、「このコードは状態をどう変えるのか」「このコードは外部に何を要求するのか」という意図がそれぞれ明確になります。

5. 変更を追跡しやすくする (Immutable Data)

状態を直接変更するのではなく、常に新しい状態オブジェクトを生成して置き換える（Immutable Data）ことで、状態の変化履歴を追跡しやすくなり、デバッグが容易になります。これも状態管理の意図を明確にする上で有効な手法です。なぜ状態がその値になったのかを、変更履歴を遡ることで理解できるようになります。

例えば、JavaScriptでオブジェクトや配列を更新する際に、スプレッド構文などを使用して新しいオブジェクト/配列を生成する手法は、このImmutable Dataの考え方に基づいています。

// Before: オブジェクトを直接変更

const user = { id: 1, name: 'Alice', active: true };
user.active = false; // 既存オブジェクトを直接変更

// After: 新しいオブジェクトを生成して状態を更新

const user = { id: 1, name: 'Alice', active: true };
// スプレッド構文で新しいオブジェクトを生成し、activeプロパティを上書き
const updatedUser = { ...user, active: false };

// updatedUser は { id: 1, name: 'Alice', active: false } となるが、
// 元の user オブジェクトは { id: 1, name: 'Alice', active: true } のまま残る（イミュータブル）

後者の手法は、変更が「新しい状態を作る」という明確な意図を持って行われていることを示します。元の状態が破壊されないため、変更前の状態と変更後の状態を比較したり、変更履歴を管理したりすることが容易になります。

状態管理パターンが提供する意図伝達の構造

Redux、Vuex、Zustand、Piniaなど、様々な状態管理ライブラリやパターンが存在します。これらの多くは、状態、状態を変更するロジック、副作用を扱うロジックを明確に分離し、データの流れを特定の方向（単一方向データフロー）に制限することで、状態管理の意図をコード上で表現するための構造を提供しています。

例えばReduxでは、以下のように役割が明確に分離されています。 * Store: アプリケーション全体の状態を保持する唯一の場所（状態の定義） * Action: 「何が起こったか」という意図を表現するプレーンなオブジェクト（変化の契機） * Reducer: 現在の状態とActionを受け取り、新しい状態を返す純粋関数（変化の規則） * Middleware / Effects: 副作用（非同期処理など）を処理する場所（副作用の分離）

このような構造に従うことで、「このファイルを見れば状態の定義がわかる」「この関数はActionを受け取って状態をどう変えるかのロジックだけが書かれている」「このモジュールを見れば、状態変化に伴って外部とやり取りする処理がわかる」といったように、コードの各部分が状態管理のどの側面に関するものなのかという意図が明確になります。

チームでの意図共有

状態管理におけるコードの意図をチーム全体で共有するためには、コーディング規約を定めることや、コードレビューを積極的に行うことが有効です。

まとめ

アプリケーションの状態管理は複雑になりがちですが、開発者の「意図」をコードで明確に表現することを意識することで、コードの可読性、保守性、そしてチーム開発効率を大きく向上させることができます。

本稿でご紹介した、状態定義の明確化、状態変更ロジックの集約と意図を込めた命名、データの流れや依存関係の表現、副作用の分離、そしてImmutable Dataの活用といった手法は、どのような状態管理アプローチを採用する場合でも応用可能な基本的な考え方です。

これらの技術を実践することで、コードを見た人が「この状態はどのようなデータで、いつ、なぜ、どのように変化し、その結果何が起こるのか」といった開発者の意図をスムーズに理解できるようになります。ぜひ日々のコーディングやチーム開発に取り入れていただき、コードで「意味」を伝える状態管理を目指してください。