Python | VS Code上でコメント／docstringを自動チェックするための設定手順

ここでは、VS Code上でコメント／docstringを自動チェックするための設定手順を、初心者でも迷わないようにステップごとに説明します。

ゴール

VS Code で Python コードを書くときに、

• docstring（関数説明）が無いと警告が出る
• コメントのスタイルミスを自動で教えてくれる
• 保存時に自動で整形（auto fix）できる
  状態を作ります。

ステップ1：必要なツールをインストール

まず、VS Codeに拡張機能とPythonライブラリを準備します。

VS Code拡張機能をインストール

1. VS Code左の拡張機能アイコン（🔌）をクリック
2. 以下を検索してインストール：
   • ✅ Python（Microsoft公式）
   • ✅ Pylint または Flake8
   • ✅ autoDocstring – Python Docstring Generator（docstring自動生成に便利）

ステップ2：Python側ライブラリを入れる

VS Code が lint を実行するために、Python環境にもリンターを入れます。

pip install pylint flake8 pydocstyle darglint

（仮想環境を使っている場合は、その中で実行）

ステップ3：VS Code の設定を編集

方法① GUI から設定する（初心者向け）

1. Ctrl + ,（または「ファイル → 設定 → 設定」）を開く
2. 検索バーに「lint」または「pylint」と入力
3. 以下の設定を確認・有効化：
   • ✅ Python › Linting: Enabled → ON
   • ✅ Python › Linting: Pylint Enabled → ON（または Flake8）
   • ✅ Python › Linting: Lint On Save → ON
4. 保存後、Pythonファイルを開くと、下線付きで警告が表示されるようになります。

方法② settings.json を直接編集（上級者向け）

VS Code右下の歯車 → 「設定（JSON）」を開き、次を追加します👇

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.linting.flake8Enabled": false,
  "python.linting.pydocstyleEnabled": true,
  "python.linting.lintOnSave": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "python.linting.pylintArgs": [
    "--disable=C0114,C0115",   // 無視したいdocstring警告（例）
    "--enable=C0116"           // 関数docstringが無いと警告する
  ],
  "python.linting.pydocstyleArgs": [
    "--convention=google"      // Googleスタイルdocstringに準拠
  ]
}

{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.linting.flake8Enabled": false,
  "python.linting.pydocstyleEnabled": true,
  "python.linting.lintOnSave": true,
  "python.formatting.provider": "black",
  "editor.formatOnSave": true,
  "python.linting.pylintArgs": [
    "--disable=C0114,C0115",   // 無視したいdocstring警告（例）
    "--enable=C0116"           // 関数docstringが無いと警告する
  ],
  "python.linting.pydocstyleArgs": [
    "--convention=google"      // Googleスタイルdocstringに準拠
  ]
}

💡補足：

• C0114 → モジュールにdocstringなし
• C0115 → クラスにdocstringなし
• C0116 → 関数にdocstringなし
• --enable／--disable で好みに合わせて切替え可能です。
• pydocstyle と併用すると「スタイル」もチェックしてくれます。

ステップ4：docstring自動生成を有効化

「autoDocstring – Python Docstring Generator」を入れておくと、関数の上で

"""doc

と打つ or
Alt + Shift + 2（デフォルトショートカット）
を押すと、関数シグネチャに合わせたテンプレートを自動生成してくれます👇

例：

def add(a, b):
    """[summary]

    Args:
        a (int): [description]
        b (int): [description]

    Returns:
        int: [description]
    """
    return a + b

def add(a, b):
    """[summary]

    Args:
        a (int): [description]
        b (int): [description]

    Returns:
        int: [description]
    """
    return a + b

ステップ5：コメント・docstringのチェック例

以下のようにdocstringが無いと、VS Codeが警告してくれます：

def greet(name):
    return f"Hello, {name}!"

def greet(name):
    return f"Hello, {name}!"

🟡 警告：

C0116: Missing function or method docstring (missing-function-docstring)

docstringを追加すると警告が消えます。

ステップ6：チーム・プロジェクト向けの設定

プロジェクトルートに .pylintrc や setup.cfg を置くと、全員で同じルールを共有できます。

例（.pylintrc）：

[MASTER]
ignore=tests

[MESSAGES CONTROL]
enable=missing-function-docstring,missing-module-docstring
disable=invalid-name

[FORMAT]
max-line-length=88

まとめ