frontend-code-quality

フロントエンドのコード品質ガイドライン

これは厳格なガイドラインです。 これらのルールに正確に従ってください。

明確で保守しやすいフロントエンドコードを書くための基本ガイドラインです。

---

1. コンポーネントのシンプルさ

ガイドライン：コンポーネントは単一の責務に集中させてください。

// ❌ Avoid: Component doing too much
function UserDashboard() {
  const [user, setUser] = useState(null);
  const [posts, setPosts] = useState([]);
  const [comments, setComments] = useState([]);
  
  useEffect(() => {
    fetch('/api/user').then(r => r.json()).then(setUser);
    fetch('/api/posts').then(r => r.json()).then(setPosts);
    fetch('/api/comments').then(r => r.json()).then(setComments);
  }, []);
  
  return (
    <div>
      {/* Complex rendering logic for user, posts, comments */}
    </div>
  );
}

// ✅ Preferred: Split into focused components
function UserDashboard() {
  return (
    <div>
      <UserProfile />
      <UserPosts />
      <UserComments />
    </div>
  );
}

ガイドライン：

• ファイルは単一の責務に集中させてください。シンプルなインターフェースを持つまとまりのあるモジュールは、200行を超えてもかまいません（約400行まで）。行数よりも内容の深さを重視してください。長さの目標を達成するためではなく、ファイルに複数の無関係な関心事が含まれる場合にのみ分割してください。
• 複雑なロジックが別の関心事に関わる場合は、カスタムフックやユーティリティ関数に切り出してください。
• JSX 内でのネストした三項演算子や複雑な条件式は避けてください。

// ❌ Avoid: Complex nested conditionals
{isLoading ? <Spinner /> : error ? <Error /> : data ? <Content data={data} /> : <Empty />}

// ✅ Preferred: Early returns or extracted logic
if (isLoading) return <Spinner />;
if (error) return <Error />;
if (!data) return <Empty />;
return <Content data={data} />;

---

2. 状態管理の明確さ

ガイドライン：状態は、できるだけ使用箇所の近くに置いてください。

// ❌ Avoid: Unnecessary state lifting
function App() {
  const [modalOpen, setModalOpen] = useState(false);
  return <UserProfile modalOpen={modalOpen} setModalOpen={setModalOpen} />;
}

// ✅ Preferred: State where it's used
function UserProfile() {
  const [modalOpen, setModalOpen] = useState(false);
  return <Modal open={modalOpen} onClose={() => setModalOpen(false)} />;
}

ガイドライン：

• 複数のコンポーネントで共有する必要がある場合にのみ、状態を上位に移してください。
• コンテキストは必要最小限に使用してください（認証、テーマ、グローバル設定のみ）。
• 2～3階層を超えるプロップスのバケツリレーは避け、代わりにコンポジションまたはコンテキストを使用してください。

// ❌ Avoid: Deep prop drilling
<Parent user={user}>
  <Child user={user}>
    <GrandChild user={user}>
      <GreatGrandChild user={user} />
    </GrandChild>
  </Child>
</Parent>

// ✅ Preferred: Context for deeply shared data
const UserContext = createContext<User | null>(null);

function Parent() {
  const user = useUser();
  return (
    <UserContext.Provider value={user}>
      <Child />
    </UserContext.Provider>
  );
}

function GreatGrandChild() {
  const user = useContext(UserContext);
  return <div>{user.name}</div>;
}

---

3. 型安全性

ガイドライン：すべてのコンポーネントインターフェースに明示的な型を定義してください。

// ❌ Avoid: Implicit or missing types
function UserCard({ user, onEdit }) {
  return <div onClick={onEdit}>{user.name}</div>;
}

// ✅ Preferred: Explicit types
interface UserCardProps {
  user: {
    id: string;
    name: string;
    email: string;
  };
  onEdit: (userId: string) => void;
}

function UserCard({ user, onEdit }: UserCardProps) {
  return <div onClick={() => onEdit(user.id)}>{user.name}</div>;
}

ガイドライン：

• any は避けてください。型が本当に不明な場合は unknown を使用してください。
• バリアントコンポーネントには判別可能なユニオン型を使用してください。
• イベントハンドラーには明示的に型を指定してください。

// ✅ Discriminated unions for variants
type ButtonProps = 
  | { variant: 'primary'; onClick: () => void }
  | { variant: 'link'; href: string };

function Button(props: ButtonProps) {
  if (props.variant === 'link') {
    return <a href={props.href}>Link</a>;
  }
  return <button onClick={props.onClick}>Button</button>;
}

// ✅ Explicit event handler types
function SearchInput() {
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    console.log(e.target.value);
  };
  
  return <input onChange={handleChange} />;
}

---

4. データ取得のパターン

ガイドライン：データ取得と表示を分離してください。

// ❌ Avoid: Fetching in component
function UserList() {
  const [users, setUsers] = useState([]);
  
  useEffect(() => {
    fetch('/api/users').then(r => r.json()).then(setUsers);
  }, []);
  
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

// ✅ Preferred: Custom hook for data fetching
function useUsers() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    fetch('/api/users')
      .then(r => r.json())
      .then(setUsers)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);
  
  return { users, loading, error };
}

function UserList() {
  const { users, loading, error } = useUsers();
  
  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;
  
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

ガイドライン：

• ローディング状態、エラー状態、空の状態を明示的に処理してください。
• レンダリング中のデータ取得は避け、フックまたはエフェクトを使用してください。
• データ取得ライブラリを使用する場合は、リクエストをキャッシュし、重複を排除してください。

// ✅ Handle all states
function DataDisplay() {
  const { data, loading, error } = useData();
  
  if (loading) return <LoadingState />;
  if (error) return <ErrorState error={error} />;
  if (!data || data.length === 0) return <EmptyState />;
  
  return <DataList data={data} />;
}

---

5. 命名規則

ガイドライン：意図が伝わる、一貫性のあるわかりやすい名前を使用してください。

// ❌ Avoid: Unclear or inconsistent names
function Card({ data, fn, flag }) {
  return <div onClick={fn}>{flag && data.txt}</div>;
}

// ✅ Preferred: Clear, consistent names
function UserCard({ user, onEdit, isEditable }: UserCardProps) {
  return <div onClick={onEdit}>{isEditable && user.name}</div>;
}

規則：

• コンポーネント：PascalCase（UserProfile.tsx）
• フック：use 接頭辞を付けた camelCase（useUserData.ts）
• ユーティリティ：camelCase（formatDate.ts）
• 定数：UPPER_SNAKE_CASE（API_BASE_URL）
• ブール値のプロップス／変数：is、has、should のいずれかを接頭辞に付ける

// ✅ Boolean naming
interface ModalProps {
  isOpen: boolean;
  hasCloseButton: boolean;
  shouldShowOverlay: boolean;
}

// ✅ Event handler naming
interface FormProps {
  onSubmit: (data: FormData) => void;
  onChange: (field: string, value: string) => void;
  onValidate: (data: FormData) => ValidationResult;
}

---

6. ファイル構成

ガイドライン：機能別ではなく、種類別に整理してください。

frontend/
├── components/          # All components
│   ├── ui/             # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Input.tsx
│   │   └── Modal.tsx
│   ├── UserProfile.tsx
│   ├── UserSettings.tsx
│   ├── PostList.tsx
│   └── PostCard.tsx
├── hooks/              # Custom hooks
│   ├── useUser.ts
│   ├── usePost.ts
│   └── useAuth.ts
├── lib/                # Utilities and helpers
│   ├── api/
│   ├── auth/
│   └── utils/
├── types/              # Type definitions
│   ├── user.ts
│   └── post.ts
└── queries/            # API queries (GraphQL, etc.)
    ├── user.ts
    └── post.ts

種類別に整理する理由：

• 再利用性が高いと、機能の境界が曖昧になります。
• 複数の機能で使用されるコンポーネントを見つけやすくなります。
• コンポーネントライブラリや共有ユーティリティに自然に適合します。

ガイドライン：

• 関連性の高いファイルはサブディレクトリにまとめてください（例：components/ui/）。
• 共有コードや再利用可能なコードは、lib/ または utils/ から利用できるようにしてください。
• ビジネスロジックと UI ロジックを分離してください。

---

関連するパターン

• コンポーネントの構成 - ディレクトリ構成のパターン
• 基本原則 - あらゆる開発に共通する原則

---

AI アシスタント向け：フロントエンドコードを作成またはレビューする際は、これらのガイドラインに従ってください。巧妙さよりも明確さと保守性を優先してください。

---

継続的な改善

このスキルで防げるはずの振る舞いについて開発者から修正を受けた場合は、同じ修正が今後必要にならないよう、このスキルに加える具体的な改訂案を提案してください。