効果的なコードコメントとJSDocの利用法 #JSDoc

コードコメントとは？

コードコメントは、コンピュータプログラムのソースコードに追加された書き込み説明やメモです。その目的は、コードを読んだり作業したりする開発者に対して、情報、文脈、または明確化を提供することです。コメントは、コード内のロジック、意図、または重要な詳細を理解するために人間が利用するものだけであり、通常、コードが実行される際にはコンピュータによって無視されます。

どんなコードに対してコメントを書いた方が良いですか？

コメントを書くことでコードが理解しやすくなりますが、しかし、全てのコードに対してコードを書くのは間違いです。なぜかと言うと、変更をする際にコードと共にコメントも変更しないといけなくなり保留しにくくなるからです。その為、仕様が複雑なモジュール/エクスポートされた関数にコメントを書くと良いでしょう。

「モジュールにコメントを追加しておけば、その機能を使用することになる他の開発者の助けになる」（達人プログラマー, 31ページ）。

どんなコメントを書くべきすですか？

コメントの書き方には多様なベストプラクティスが存在しますが、ここでは以下の例を参考にご紹介します。

「コメントは「なぜこれが必要なのか」、すなわちその目的とゴールの記述にとどめておくべきでしょう。「どのようにして実行しているのか」はコード自体に記されているため、冗長な情報であり、DRY原則に違反しているのです（達人プログラマー, 31ページ）。

コメントの正しい使い方

背景や複雑なコードの説明

コメントは開発者が互いの作業をスムーズに理解するのに役立ちます。コードが複雑で他の開発者にすぐに理解されない場合には、特にコメントを書くことが役立ちます。
ユースケース: チームプロジェクトでは、特定のデザインの選択に対する背景を説明するコメントは、チームメンバー間で理解を深め、学習コストを削減します。

// このデザインの選択は、頻繁なデータの更新に対してパフォーマンスを最適化しています
const updateData = (newData: any[]) => {
  // 実装の詳細...
};

将来の参照のためのもの

コメントは自己文書化の手法の一つで、将来の開発者や自分自身がコードベースを理解するのに役立ちます。
ユースケース: 数ヶ月後にコードを再訪する場合、明確なコメントは意思決定や戦略を思い出させる道標となります。

// TODO: モジュラリティの向上を目的として、このセクションのリファクタリングを行う。
// NOTE: 以下の実装方法になっている理由の詳細についてはこちらを参照にしてください：　https://notion.jp/wiki...
function complexFunction() {
  ...
}

アノテーションコメントについてもっと知りたい場合はこの記事を参考にしてください。

コメントの間違った使い方

過剰なコメントに関する注意:

特に当たり前なことを述べたりするコメントが多すぎると、コードが混乱し、可読性が低下します。自己説明的なコードにはコメントは不要です。
例: 配列を繰り返し処理する単純なループを説明するコメントは、ループが適切に命名されていてわかりやすい場合、不要かもしれません。

// 配列をループ処理する
for (let i = 0; i < array.length; i++) {
  // 各要素に対する操作...
}

古くなったコメント　コードが変更したらコメントも変更する:

現在のコードの状態と一致していないコメントは、開発者を誤導する可能性があります。
例: 関数の目的を説明するコメントが古くなった場合、混乱やエラーの原因になる可能性があります。

// 二つの数を足す関数
function add(a, b, c) {
  return a + b + c; 
}

コメントの弱点でもあるが、コードが変更したらコメントも変更することがmustです！

JSDocでコメントを書く

普通のコメントよりも、JSDocのシンタックスを使用してコメントを書くことによってコードをより理解しやすくすることができます。

JSDocとは？

JSDocはJavaScriptコードに構造化されたコメントを追加するための構文・シンタックスです。これは、関数、変数、クラスなどをドキュメント化するために使用され、それらの目的、パラメータ、戻り値、および使用例を説明する標準化された方法を提供します。

JSDocコメントのメリット

明確さと可読性: 開発者は関数の目的、受け入れるパラメータの種類、および返す値を迅速に把握できます。
IDEホバーサポート: 開発者がIDEでcalculateTotalPrice関数にカーソルを合わせると、その関数の目的、受け入れるパラメータのタイプ、期待される戻り値の概要、さらには使用例を、関数全体を読まずに即座に確認できます。

/**
 * この関数は、ショッピングカート内の商品の合計金額を計算します。
 *
 * @param {CartItem[]} cartItems - ショッピングカート内の商品を表すオブジェクトの配列。
 * @returns {number} カート内のすべての商品の合計金額。
 *
 * @throws {Error} カートアイテムの配列が空の場合。
 *
 * @example
 * const cartItems = [
 *   { name: 'Product A', price: 20.99, quantity: 2 },
 *   { name: 'Product B', price: 15.49, quantity: 1 },
 * ];
 * const totalPrice = calculateTotalPrice(cartItems); // 57.47が返されます
 */
export function calculateTotalPrice(cartItems: CartItem[]): number {
  // 実装...
}

上のcalculateTotalPriceを他のファイルでimportしている場合は、カーソルを合わせると、その関数のJSDocコメント内容が表示されて関数の使用方法の調査や理解がより簡単にできます。

JSDocについてもっと知りたい場合はこの記事を参考にしてください。

まとめ

コメントの効果的な利用は、複雑なコードや他の開発者にとって即座に理解しづらいコードを説明する際に重要です。
コードが自己説明的である場合、過剰なコメントはコードのクラッターとなり、可読性を低下させる可能性があります。
過去の状態と合わないコメントは誤解を招き、エラーの原因になる可能性があります。
JSDocを使用すると、コード内に構造化されたコメントを追加し、開発者に関数や変数の目的、パラメータ、戻り値、使用例などを標準化された形で提供できます。

参考

初心者がJSDocを調べてた
 TODO: 以外のアノテーションコメントをまとめた

効果的なコードコメントとJSDocの利用法