多言語対応 docstring/コメントの管理

多言語対応の docstring/コメントを体系的に管理し、高品質なドキュメントを維持します。

使い方

bash
# 言語を自動検出して実行
「docstring がないクラス・関数に追加し、基準を満たさないコメントを更新してください」

# 言語を指定して実行
/update-doc-string --lang python
「Python ファイルの docstring を PEP 257 準拠で更新してください」

# 特定ディレクトリのドキュメント整備
「src/components/ 配下の関数に JSDoc を追加してください」

オプション

• --lang <en|ja> : ドキュメントの記述言語 (デフォルト: 既存コメントから自動判定、なければ en)
• --style <スタイル> : ドキュメントスタイルを指定 (言語固有のデフォルトあり)
• --marker <true|false> : Claude マーカーを付与するか (デフォルト: true)

基本例

bash
# 1. 対象ファイルの分析 (プログラミング言語は自動検出)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
「docstring が不足している要素 (コメント行数 0 または 30 文字未満) を特定してください」

# 2. ドキュメント追加 (言語自動判定)
「特定された要素に言語固有の必須要素を含む docstring を追加してください」
# → 既存コメントに日本語があれば日本語で、なければ英語で記述

# 3. ドキュメント追加 (明示的に英語指定)
/update-doc-string --lang en
「Add docstrings with required elements to the identified elements」

# 4. マーカー確認
「追加・更新したすべての docstring に Claude マーカーがあることを確認してください」

実行手順

1. 対象要素の優先順位

1. 🔴 最優先: docstring/コメントがない要素 (コメント行数 0)
2. 🟡 次優先: 基準を満たさない要素 (30 文字未満または必須要素欠如)
3. 🟢 確認対象: Claude マーカーがない既存コメント

対象要素 (言語共通):

• Class/クラス定義
• Function/関数・メソッド
• Module/モジュール (Python, Go)
• Enum/列挙型
• Interface/インターフェース (TypeScript, Go)

2. 言語別記述ルール

Python (PEP 257):

python
# 日本語版 (デフォルト)
def calculate_total(items: List[Item]) -> float:
    """アイテムリストの合計金額を計算します。(30-60 文字)

    各アイテムの価格と数量を掛け合わせ、税込み合計を返します。
    空のリストの場合は 0.0 を返します。(50-200 文字)

    Args:
        items: 計算対象のアイテムリスト

    Returns:
        税込み合計金額

    Generated by Claude 🤖
    """

# 英語版 (--lang en)
def calculate_total(items: List[Item]) -> float:
    """Calculate the total amount for a list of items. (30-60 chars)

    Multiplies the price and quantity of each item and returns
    the total with tax. Returns 0.0 for empty lists. (50-200 chars)

    Args:
        items: List of items to calculate

    Returns:
        Total amount with tax

    Generated by Claude 🤖
    """

JavaScript/TypeScript (JSDoc):

javascript
/**
 * ユーザープロフィールを表示するコンポーネントです。(30-60 文字)
 *
 * アバター画像、ユーザー名、ステータス情報を表示し、
 * クリック時にプロフィール詳細画面へ遷移します。(50-200 文字)
 *
 * @param {Object} props - コンポーネントのプロパティ
 * @param {string} props.userId - ユーザー ID
 * @param {boolean} [props.showStatus=true] - ステータス表示フラグ
 * @returns {JSX.Element} レンダリングされたコンポーネント
 *
 * @generated by Claude 🤖
 */
const UserProfile = ({ userId, showStatus = true }) => {

Go:

go
// CalculateTotal はアイテムリストの合計金額を計算します。(30-60 文字)
//
// 各アイテムの価格と数量を掛け合わせ、税込み合計を返します。
// 空のスライスの場合は 0.0 を返します。(50-200 文字)
//
// Generated by Claude 🤖
func CalculateTotal(items []Item) float64 {

Rust:

rust
/// アイテムリストの合計金額を計算します。(30-60 文字)
///
/// 各アイテムの価格と数量を掛け合わせ、税込み合計を返します。
/// 空のベクタの場合は 0.0 を返します。(50-200 文字)
///
/// Generated by Claude 🤖
pub fn calculate_total(items: &[Item]) -> f64 {

Dart (DartDoc):

dart
/// ユーザープロフィールを表示する Widget です。(30-60 文字)
///
/// アバター画像、ユーザー名、ステータス情報を縦に配置し、
/// タップ時にプロフィール詳細画面へ遷移します。(50-200 文字)
///
/// Generated by Claude 🤖
class UserProfileWidget extends StatelessWidget {

3. 既存コンテンツ保持ルール

1. 既存コメントが基準を満たす場合: そのまま保持 (新規追加しない)

• 基準: 30 文字以上かつ必須要素 (概要・詳細・マーカー) を含む

1. 既存コメントが基準を満たさない場合: 完全に置き換え (重複させない)
2. 既存コメントがない場合: 新しいコメントを追加

保持すべき重要情報:

• URL やリンク: See also:, @see, 参照: など
• TODO コメント: TODO:, FIXME:, XXX: 形式
• 注意事項: Note:, Warning:, 注意: など
• 使用例: Example:, 例:, # Examples など
• 既存のパラメータ・戻り値説明

言語別設定

yaml
# 言語別デフォルト設定
languages:
  python:
    style: "google" # google, numpy, sphinx
    indent: 4
    quotes: '"""'

  javascript:
    style: "jsdoc"
    indent: 2
    prefix: "/**"
    suffix: "*/"

  typescript:
    style: "tsdoc"
    indent: 2
    prefix: "/**"
    suffix: "*/"

  go:
    style: "godoc"
    indent: 0
    prefix: "//"

  rust:
    style: "rustdoc"
    indent: 0
    prefix: "///"

  dart:
    style: "dartdoc"
    indent: 0
    prefix: "///"

品質チェックリスト

• ✅ 文字数: 概要 30-60 文字、詳細 50-200 文字を厳守
• ✅ 必須要素: 概要・詳細説明・Claude マーカーの 3 要素を必ず含む
• ✅ 完全性: 役割・使用コンテキスト・注意点を記載
• ✅ 言語規約: 各言語の公式スタイルガイドに準拠
• ✅ 例外: エラー・例外の説明 (該当する場合)
• ✅ 正確性: 実装を分析し、事実に基づいた記述のみ

注意事項

🔴 絶対禁止事項:

• ❌ ドキュメントコメント以外のコード変更
• ❌ 実装詳細に関する推測 (事実のみ記載)
• ❌ 言語規約に反するフォーマット
• ❌ 既存の型アノテーションの削除・変更
• ❌ 既存コメントとの重複
• ❌ テストファイルへの文字数基準未満のコメント

実行と検証:

bash
# 実行結果の記録
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# 既存コメントから言語を自動判定
# 日本語文字 (ひらがな・カタカナ・漢字) を検出したら ja、それ以外は en
DOC_LANGUAGE="en"  # デフォルト
if grep -r '[ぁ-んァ-ヶー一-龠]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
  DOC_LANGUAGE="ja"
fi

# プログラミング言語の自動検出と静的解析
if [ -f "*.py" ]; then
  pylint --disable=all --enable=missing-docstring .
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
  eslint . --rule 'jsdoc/require-jsdoc: error'
elif [ -f "*.go" ]; then
  golint ./...
elif [ -f "*.rs" ]; then
  cargo doc --no-deps
elif [ -f "*.dart" ]; then
  melos analyze
fi

if [ $? -ne 0 ]; then
  echo "🔴 エラー: 静的解析が失敗しました"
  exit 1
fi

# 実行サマリーの出力
echo "📊 実行結果:"
echo "- ドキュメント言語: $DOC_LANGUAGE"
echo "- 追加したコメント: $ADDED_COMMENTS 件"
echo "- 更新したコメント: $UPDATED_COMMENTS 件"
echo "- エラー発生数: $ERRORS 件"

実行成功基準

1. 完了判定: 以下をすべて満たす場合に成功

• 言語固有の静的解析が PASSED
• エラー発生数が 0
• 追加・更新したコメントがすべて基準を満たす

1. 部分成功: 以下の場合

• エラー発生数が 5 件未満
• 全体の 90% 以上が基準を満たす

1. 失敗: 以下の場合

• 静的解析が FAILED
• エラー発生数が 5 件以上

Claude との連携

bash
# プロジェクト全体の分析 (言語自動判定)
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
/update-doc-string
「このプロジェクトの docstring を言語別のベストプラクティスに従って更新して」
# → 既存コメントに日本語があれば ja、なければ en で実行

# 明示的に英語ドキュメントで実行
/update-doc-string --lang en
"Update docstrings following language-specific best practices"

# 明示的に日本語ドキュメントで実行
/update-doc-string --lang ja
「このプロジェクトの docstring を言語別のベストプラクティスに従って更新して」

# マーカーなしで実行 (言語自動判定)
/update-doc-string --marker false
"Improve existing docstrings without adding Claude markers"

# 英語ドキュメント、マーカーなし
/update-doc-string --lang en --marker false
"Improve existing docstrings without adding Claude markers"