コメント（// と /* */ と {/* */}）

// 一行コメント — // から行末までがコメントになります。
const count = 0; // 行末コメント — コードの後にも書けます。

/*
  ブロックコメント — /* から */ までの範囲がコメントになります。
  複数行にわたる説明を書くときに使います。
*/

/**
 * JSDoc コメント — /** で始めるブロックコメントです。
 * 関数コンポーネントや Server Actions の直前に書きます。
 * @param props - コンポーネントの props
 * @returns JSX 要素
 */

// TypeScript の型チェックを制御するコメント。
// @ts-ignore — 次の行の型エラーを無視します。
// @ts-expect-error — 次の行に型エラーが存在することを意図的に宣言します。

同じ処理は次のようにも書けます。

// JSX 内のコメント — 中括弧でラップした /* */ を使います。
export default function Page() {
  return (
    <main>
      {/* JSX 内のコメントはこの形式で書きます。 */}
      <h1>タイトル</h1>
    </main>
  );
}

どちらも次の行の TypeScript 型エラーを無視しますが、動作に違いがあります。

// @ts-ignore の使用例。
// @ts-ignore — 外部ライブラリの型定義が不完全なため一時的に無視します。
const result = externalLib.doSomething();

// @ts-expect-error の使用例。
// @ts-expect-error — テストコードで意図的に不正な値を渡しています。
const parsed = parseInt("not a number", 10);

Next.js の関数コンポーネント・Server Actions・Route Handlers に JSDoc コメントを書くと、VS Code などのエディタがホバー表示でドキュメントを表示します。TypeScript を使っているプロジェクトでも、JSDoc で説明を補足できます。

Page コンポーネントと Server Actions

app/users/page.tsx

// このファイルは Server Component として動作します（デフォルト）。
// クライアント側の JavaScript には含まれません。

interface User {
  id: number;
  name: string;
  email: string;
}

/**
 * ユーザー一覧ページのサーバーコンポーネントです。
 * データは fetch でサーバーサイドから取得します。
 */
export default async function UsersPage() {
  /*
    fetch の第2引数でキャッシュ動作を制御します。
    { cache: 'no-store' } で毎回最新データを取得します（SSR 相当）。
    { next: { revalidate: 60 } } で60秒ごとに再検証します（ISR 相当）。
  */
  const res = await fetch('https://api.example.com/users', {
    cache: 'no-store',
  });

  const users: User[] = await res.json();

  return (
    <main>
      {/* ページタイトル */}
      <h1>ユーザー一覧</h1>

      {/* ユーザーが存在しない場合のフォールバック。 */}
      {users.length === 0 && <p>ユーザーが見つかりません。</p>}

      <ul>
        {users.map((user) => (
          // key には一意な id を使います。
          <li key={user.id}>{user.name} — {user.email}</li>
        ))}
      </ul>
    </main>
  );
}

app/users/actions.ts

'use server';

// Server Actions はファイル先頭またはファイル単位で 'use server' を宣言します。

/**
 * 新しいユーザーを作成するサーバーアクションです。
 * @param formData - フォームから送信されたデータ
 * @returns 作成されたユーザーオブジェクト、またはエラーメッセージ
 * @throws ネットワークエラーの場合は例外をスローします。
 */
export async function createUser(formData: FormData) {
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;

  if (!name || !email) {
    // バリデーションエラー: 必須フィールドが未入力。
    return { error: 'name と email は必須です。' };
  }

  /*
    外部 API への POST リクエスト。
    エラーハンドリングは呼び出し元で try/catch を使って処理します。
  */
  const res = await fetch('https://api.example.com/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name, email }),
  });

  return res.json();
}

next.config.js のコメント

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  /*
    画像の外部ドメインを許可します。
    next/image コンポーネントで外部 URL の画像を表示する際に必要です。
  */
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
        // このドメインのみ許可します。ワイルドカードは使わないよう注意。
      },
    ],
  },

  // 実験的機能の有効化。Next.js のメジャーアップデートで変更される可能性があります。
  experimental: {
    serverActions: {
      bodySizeLimit: '2mb', // フォーム送信の上限。デフォルトは 1mb。
    },
  },
};

module.exports = nextConfig;

Next.js のコメント記法は TypeScript/JavaScript と同じです。TypeScript ファイルでは一行コメント・ブロックコメント・JSDoc コメントが使えます。JSX の返却値の中では『{/* */}』を使います。Next.js に特有のコメントとして、TypeScript の型エラーを制御する『// @ts-ignore』・『// @ts-expect-error』があります。これらを使う場合は、なぜ型エラーを無視しているかの理由を必ずコメントに添えます。

Server Actions・Route Handlers・関数コンポーネントには JSDoc コメントを書いておくと、VS Code がホバー表示でドキュメントを提示するようになります。next.config.js などの設定ファイルでも、各設定オプションの意図をコメントで補足しておくと後からの参照コストが下がります。

コメントは「何をしているか」ではなく「なぜそうしているか」を書くと効果的です。コードを読めば明らかな処理を逐一コメントで説明するのはノイズになります。変更履歴や削除したコードをコメントとして残す必要もありません。それらはバージョン管理（git）で追跡できます。