コード ドキュメンテーション

目次

• 概要
• 使用するとき
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

JSDoc、Python docstrings、JavaDoc、インラインコメントなどの言語固有の標準を使用して、明確で包括的なコード ドキュメンテーションを作成します。

使用するとき

• 関数とクラスのドキュメンテーション
• JavaScript/TypeScript の JSDoc
• Python docstrings
• Java の JavaDoc
• インラインコメント
• コードから生成される API ドキュメンテーション
• 型定義
• コード内の使用例

クイックスタート

最小限の動作例：

/**
 * Calculates the total price including tax and discount.
 *
 * @param {number} basePrice - The base price before tax and discount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount
 * @returns {number} The final price after tax and discount
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * const price = calculateTotalPrice(100, 0.08, 10);
 * console.log(price); // 98
 *
 * @example
 * // Without discount
 * const price = calculateTotalPrice(100, 0.08);
 * console.log(price); // 108
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error("Price and tax rate must be non-negative");
  }
  return basePrice * (1 + taxRate) - discount;
}

// ... (see reference guides for full implementation)

リファレンスガイド

references/ ディレクトリの詳細な実装：

ベストプラクティス

✅ DO（すべき）

• 公開 API を詳しくドキュメント化する
• 使用例を含める
• パラメータと戻り値をドキュメント化する
• 発生する可能性のある例外やエラーを明記する
• 言語固有の標準（JSDoc、docstrings など）を使用する
• コメントを最新の状態に保つ
• 「何」ではなく「なぜ」をドキュメント化する
• エッジケースと注意事項を含める
• 関連する関数へのリンクを追加する
• 型定義をドキュメント化する
• 一貫したフォーマットを使用する

❌ DON'T（すべきでない）

• コメントで明らかなことを述べる
• コメントアウトされたコードを残す
• 誤解を招くコメントを書く
• 複雑な関数の例を省略する
• あいまいなパラメータの説明を使用する
• コードが変更されときにドキュメントの更新を忘れる
• 単純なコードに過度なコメントを付ける