GPTを活用してコードにJSDoc形式のコメントを追記：効率的なドキュメント作成の実演と活用法

ChatGPTはコード生成だけでなく、コメントやドキュメントを自動で追加するサポートも可能です。特に、JSDoc形式を活用したコメントの追加は、コードの可読性とメンテナンス性を向上させる効果的な方法です。本記事では、GPTを用いてJSDoc形式でコメントを追記する方法を実演し、その活用法や注意点について詳しく解説します。

1. JSDoc形式の概要とメリット

1.1 JSDocとは

JSDocは、JavaScriptコードのドキュメントを記述するためのコメント形式です。関数や変数に対して、動作や引数、戻り値の説明を簡潔に記載できます。

1.2 JSDoc形式を使うメリット

コードの可読性向上：開発者が関数や変数の意図を簡単に理解できる。
開発効率の向上：エディタがJSDocをもとにコード補完や型チェックを提供。
チーム開発での一貫性：ドキュメントの統一が図れる。

2. 実演：GPTにJSDoc形式のコメントを追加してもらう

以下に、実際のコードとGPTによるコメント追記の流れを示します。

2.1 サンプルコードの準備

次のコードは、配列内の文字列を大文字に変換する関数です。

function capitalizeStrings(strings) {
  return strings.map(str => str.toUpperCase());
}

// 実行例
console.log(capitalizeStrings(["hello", "world"]));

このコードに対して、GPTにJSDoc形式のコメントを追加するリクエストを送ります。

2.2 GPTへのリクエスト

GPTに以下のリクエストを送信します：

“このコードにJSDoc形式でコメントを追加してください。”

GPTが生成したコード：

/**
 * Converts all strings in an array to uppercase.
 * 
 * @param {string[]} strings - An array of strings to be converted to uppercase.
 * @returns {string[]} An array of strings converted to uppercase.
 */
function capitalizeStrings(strings) {
  return strings.map(str => str.toUpperCase());
}

// 実行例
console.log(capitalizeStrings(["hello", "world"])); // 結果: ["HELLO", "WORLD"]

ポイント：

@paramタグで引数の型と説明を記載。
@returnsタグで戻り値の型と動作を説明。

2.3 コメントを追記したコードの利便性

このコードは、以下のようなメリットをもたらします：

関数の動作が一目でわかる。
IDEやエディタがJSDocを解析し、補完機能を提供。

3. JSDoc形式コメントを追加する際の注意点

3.1 コメントを過剰にしない

JSDoc形式はシンプルさが重要です。冗長な説明は避け、必要最低限の情報に留めましょう。

3.2 型情報を正確に記載する

特に、オブジェクトやカスタム型を扱う場合は正確に記載する必要があります。

例：

/**
 * @typedef {Object} User
 * @property {string} name - The name of the user.
 * @property {number} age - The age of the user.
 */

/**
 * Retrieves user details.
 * 
 * @returns {User} The details of the user.
 */
function getUser() {
  return { name: "John Doe", age: 30 };
}

3.3 自動生成されたコメントを検証する

GPTが追加したコメントが誤解を招く場合もあります。適宜修正して正確な内容にする必要があります。

4. GPTを活用した応用例

4.1 既存コードへのコメント追加

大量の既存コードにもJSDoc形式のコメントを効率的に追加可能です。

リクエスト例：

“以下のコード全体にJSDoc形式のコメントを追加してください。”

4.2 複雑な関数へのコメント

引数が複数ある場合やネストが深い場合も対応可能です。

例：

/**
 * Filters an array of objects based on a condition.
 * 
 * @param {Object[]} items - The array of objects to filter.
 * @param {function(Object): boolean} predicate - The function used to filter the objects.
 * @returns {Object[]} The filtered array of objects.
 */
function filterItems(items, predicate) {
  return items.filter(predicate);
}

5. コメント自動生成ツールとの比較

GPTはJSDoc形式コメントの生成に優れていますが、専用ツールも選択肢です。

ツール	特徴
ChatGPT	柔軟性が高く、文脈に応じたコメントが可能。
ESDoc	JSDoc形式の自動生成に特化。
TypeScript	型アノテーションがコメントの一部を補完可能。

6. ChatGPT活用の注意点

6.1 コンテキストの提供が重要

GPTはコードの文脈を理解してコメントを生成します。リクエスト時にコードの意図や背景を簡潔に説明することで、適切なコメントが得られます。

例：

「この関数はAPIからデータを取得してキャッシュします。JSDoc形式でコメントを追加してください。」

6.2 必ずレビューを行う

生成されたコメントが正しいとは限りません。開発者自身が内容を確認し、必要に応じて修正を行いましょう。

7. ChatGPTを活用した効率的なコメント追加の流れ

コードを準備する：コメントを追加したいコードを明確にする。
リクエストを送信する：「このコードにJSDoc形式のコメントを追加してください」と指示する。
生成されたコメントを確認：内容を精査し、誤りや不足があれば修正。
コードに統合：コメント付きのコードをプロジェクトに組み込む。

8. 結論

GPTを活用してJSDoc形式のコメントを追記することで、コードのドキュメント作成が効率化され、開発プロセス全体の生産性が向上します。ただし、自動生成されたコメントを過信せず、必ず内容を確認して適切に修正することが重要です。ChatGPTを補助ツールとして活用することで、開発の質を高めつつ、効率的なチーム作業を実現しましょう。

ChatGPT コード生成システム設計システム開発業務効率化