ファイル命名規則から考えるコードベースの管理と探索性

はじめに

大規模なReactプロジェクトでは、数百のコンポーネントファイルを効率的に管理する必要があります。開発者は日々、これらのファイルを視覚的に認識し、その情報を解釈して意味を理解します。適切なファイル命名規則は、この課題を解決する重要な要素となります。

Reactプロジェクトにおけるファイル命名の実践

コンポーネントファイルの命名

Reactプロジェクトでは、コンポーネントファイルに特有の命名パターンが存在します。最も代表的な例が .tsx 拡張子の使用です。これは TypeScript と JSX の機能を組み合わせた特殊なファイル形式を示しています。

// 推奨されるディレクトリ構造
src/
  components/
    Button/
      Button.tsx         // メインコンポーネント
      Button.test.tsx    // テストファイル
      Button.stories.tsx // Storybookファイル

Storybookとの統合

Storybookを使用する場合、コンポーネントのストーリーファイルには .stories.tsx という拡張子を使用します。この命名規則により、以下の3つの情報が明確に示されます：

// Button.stories.tsx
export default {
  title: 'Components/Button',
  component: Button,
} as Meta<typeof Button>;

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Click me',
  },
};

システマティックなファイル管理と探索

プログラマティックな探索の実現

プロジェクトが大規模化すると、コマンドラインインターフェースを使用して特定のファイルを検索したり、一括で処理を行ったりする必要性が高まります。

# Storybookファイルの検索
find ./src -name "*.stories.tsx"

# テストファイルの一括実行
find ./src -name "*.test.tsx" -exec yarn test {} \;

マシンリーダブルな命名規則の利点

ファイル名にタグのような意味を持つ情報を含めることで、以下のような利点が生まれます：

CI/CDパイプラインでの自動化

# .github/workflows/component-checks.yml
name: Component Checks
jobs:
  verify-components:
    steps:
      - name: Test Storybook Files
        run: find . -name "*.stories.tsx" -exec yarn test-storybook {} \;

リンターでの命名規則チェック

// .eslintrc.js
module.exports = {
  rules: {
    'filename-naming-convention': [
      'error',
      {
        'src/components/**/*.tsx': 'PascalCase',
        'src/components/**/*.stories.tsx': 'PascalCase.stories'
      }
    ]
  }
};

セキュリティ考慮事項

ファイル命名時には、以下のセキュリティ考慮事項に注意が必要です：

APIキーやパスワードなどの機密情報を含めない
内部的なビジネスロジックを示唆する名前を避ける
公開リポジトリでの社内コードネームの使用を避ける

まとめ

適切なファイル命名規則は、開発者の理解しやすさだけでなく、プログラマティックな処理のしやすさにも大きく影響します。特に大規模なプロジェクトでは、こうした規則の重要性がより顕著となります。

実践のためのステップ

既存プロジェクトのファイル命名パターンを分析する
チーム内で命名規則のガイドラインを作成する
リンターやCIでの自動チェックを導入する
定期的なレビューと改善を行う

P.S.
この記事はボイスレコーダーに録音したものをClaudeに整形、意味の抽出、文章化してみた内容を試してみたものになっています。