【Python入門】Docstringの書き方ガイド｜関数・クラス・モジュールを丁寧に記述しよう！

1. はじめに｜Docstringってなに？なんで使うの？

Pythonでプログラムを書いていると、関数やクラスのすぐ下に """ 〜 """ で囲まれた説明文を見かけたこと、ありませんか？
それが Docstring（ドッグストリング） と呼ばれるものです。

Docstringは、関数・クラス・モジュールの「使い方や目的」を説明するための特別なコメントです。
Pythonのコードに直接影響するわけではないけれど、とっても重要な役割を持っています。

たとえば、次のようなコードがあるとしましょう：

def greet(name):
    """指定された名前で挨拶を表示する関数"""
    print(f"こんにちは、{name}さん！")

この関数にカーソルを合わせたり、ヘルプを表示させたりすると、"""〜""" に書かれた説明が出てくるんです。
つまり、「この関数は何をするのか？」をドキュメントとして明示できるのがDocstringの最大の魅力です。

---

Docstringを使う理由は？

Docstringには、以下のようなメリットがあります：

• 🔍 他の人がコードを見たときに、すぐに使い方がわかる
• 🧠 自分が後で見直すときにも、「何のために書いたか」が思い出しやすい
• 🧰 VS CodeやPyCharmなどのエディターでの補助機能にも使われる

たとえるなら、Docstringは「家電製品に付いてくる取扱説明書」のようなものです。
コードの動かし方や使い方がひと目でわかると、読む人も書いた人もラクになりますよね。

---

2. Docstringの役割と書くメリット

Docstring（ドッグストリング）は、Pythonのコードの中に書く“説明書”のようなもの。
でもただのコメントじゃなくて、**ちゃんとPythonに認識される「公式な説明文」**なんです。

ここでは、Docstringがなぜ便利なのか、どう役立つのかをわかりやすく紹介します！

---

✅ コードを「読む人」にやさしい

Docstringの一番の役割は、そのコードが「何をするか」を伝えること。
たとえば、関数にどんな引数を渡せばいいのか、どんな値が返ってくるのか──
そういった「使い方」がコード内に書かれていれば、関数の中身をわざわざ読まなくても済みます。

とくに複雑なコードや、他の人と共有するプログラムではこのメリットが絶大！

---

🧠 自分の記憶の補助にもなる

「あれ、この関数って何のために作ったんだっけ？」

そんなときも、Docstringがあればすぐに思い出せます。
人間は数週間前に書いたコードの意味を忘れるもの。
未来の自分のために書いておくDocstringは、まさに“備えあれば憂いなし”です！

---

🛠 開発ツールと連携できる

PyCharmやVS Codeのようなエディタでは、Docstringの内容がツールチップ（ヘルプ表示）として自動表示されます。
関数にカーソルを合わせると説明がポップアップ表示されたり、引数の意味が確認できたり──
こうした補助機能はDocstringがあるからこそ活きてくるんです。

また、help() 関数で関数やクラスの説明を確認するときにも、Docstringの内容がそのまま出力されます。

help(greet)

---

📘 ドキュメント自動生成にも使える

Sphinxなどのドキュメント生成ツールを使えば、Docstringからプログラムの取扱説明書を自動で作ることもできます。
チーム開発やライブラリ公開の場面でも大活躍！

---

3. Docstringの基本構文と記述場所

Docstring（ドッグストリング）は、Pythonで特別な書き方が決まっている「説明文」です。
記述する場所やルールに沿って書くことで、Pythonやエディタに正しく認識してもらえます。

この章では、Docstringの基本的な構文と、どこに書くかをわかりやすく解説していきます！

---

📌 Docstringの基本構文

Docstringは、三重のダブルクォート（"""）で囲んだ文字列として記述します。

def greet(name):
    """
    指定された名前で挨拶を表示する関数。
    """
    print(f"こんにちは、{name}さん！")

Pythonではこの """説明文""" を、通常の文字列ではなく特別な「説明用文字列」として扱います。
そのため、コメント（#）とは違って、help() などのツールで自動的に読み取られるんです。

---

🧭 Docstringを書く場所

Docstringは、以下の3つの場所で使えます。それぞれ見ていきましょう。

---

① モジュール（Pythonファイル）に対するDocstring

Pythonファイルの**一番上（import文より前）**に記述します。

"""ユーティリティ関数をまとめたモジュール。"""

import math

def area_of_circle(radius):
    """半径から円の面積を計算する関数。"""
    return math.pi * radius ** 2

ここには、そのモジュール全体の目的や使い方を簡単に書いておくと便利です。

---

② クラスに対するDocstring

class の直下、最初のインデント内に書きます。

class Person:
    """
    人物を表すクラス。

    Attributes:
        name (str): 名前
        age (int): 年齢
    """
    def __init__(self, name, age):
        self.name = name
        self.age = age

そのクラスが何を表すか・どう使うか・どんな属性があるかなどを書くと、後から読みやすくなります。

---

③ 関数・メソッドに対するDocstring

def の直下に書きます。引数や戻り値の説明もここに含めることが多いです。

def multiply(a, b):
    """
    2つの数値を掛け算して結果を返す。

    Args:
        a (int): 最初の数値
        b (int): 2番目の数値

    Returns:
        int: 掛け算の結果
    """
    return a * b

関数が何をするか＋引数と戻り値の説明を書くのが基本です。
こうすることで、使う人が中身を読まなくても理解できます。

---

4. Docstringの代表的なスタイル

Docstring（ドッグストリング）には、**いくつかの「書き方のスタイル（形式）」**があります。
どのスタイルを使ってもPythonとしては正しく動作しますが、プロジェクトやチームによって好まれるスタイルが異なることもあります。

ここでは、Pythonでよく使われている2つの代表的なスタイルをご紹介します。

---

🧾 ① reStructuredText（リストラクチャードテキスト）スタイル

Python公式ドキュメントで採用されているスタイルです。
Sphinxなどのドキュメント自動生成ツールとの相性が良く、詳細な記述に向いています。

def add(a, b):
    """
    2つの数値を加算する。

    :param a: 最初の数値
    :type a: int
    :param b: 2番目の数値
    :type b: int
    :return: 加算結果
    :rtype: int
    :raises TypeError: 引数が数値でない場合
    """
    return a + b

• :param 名前: で引数の説明
• :type 名前: で引数の型
• :return: / :rtype: で戻り値の説明
• :raises: で発生する例外の説明

ちょっと書くのが大変そうですが、そのぶん詳細で丁寧なドキュメントになります。

---

📄 ② Googleスタイル

Googleが提唱した、よりシンプルで読みやすいスタイルです。
近年はこの形式を採用するプロジェクトも増えてきています。

def add(a, b):
    """
    2つの数値を加算する。

    Args:
        a (int): 最初の数値
        b (int): 2番目の数値

    Returns:
        int: 加算結果

    Raises:
        TypeError: 引数が数値でない場合
    """
    return a + b

• Args: で引数をまとめて説明
• Returns: で戻り値を記載
• Raises: で例外の説明を記述

見た目がコンパクトで、自然な日本語や英語と混ぜて書きやすいのがポイントです。

---

❓どっちを使えばいいの？

どちらでもOKですが、以下のように使い分けるのがオススメです。

シーン	スタイルのおすすめ
Sphinxでドキュメント作成	reStructuredTextスタイル
チームで統一されたルール有	指定されたスタイルに従う
個人開発や学習用コード	Googleスタイル（見やすい）

---

5. 実践！関数・クラスにDocstringをつけてみよう

ここからは、実際にDocstringを書いてみましょう！
関数やクラスに説明を追加する方法を、GoogleスタイルとreStructuredTextスタイルの両方で紹介します。
どちらも見比べて、自分に合ったスタイルを見つけてみてくださいね。

---

✏️ 関数へのDocstringの記述例

🔹 Googleスタイル

def divide(a, b):
    """
    2つの数値を割り算する。

    Args:
        a (float): 割られる数
        b (float): 割る数（0は不可）

    Returns:
        float: 割り算の結果

    Raises:
        ZeroDivisionError: bが0の場合に発生
    """
    if b == 0:
        raise ZeroDivisionError("0で割ることはできません。")
    return a / b

🔹 reStructuredTextスタイル

def divide(a, b):
    """
    2つの数値を割り算する。

    :param a: 割られる数
    :type a: float
    :param b: 割る数（0は不可）
    :type b: float
    :return: 割り算の結果
    :rtype: float
    :raises ZeroDivisionError: bが0の場合に発生
    """
    if b == 0:
        raise ZeroDivisionError("0で割ることはできません。")
    return a / b

どちらもやっていることは同じですが、書き方が少し違うだけなんです。
スタイルが違っても、伝えたい内容は変わりません。

---

🧱 クラスへのDocstringの記述例（Googleスタイル）

class Circle:
    """
    円の半径を元に面積や直径を計算するクラス。

    Attributes:
        radius (float): 円の半径
    """

    def __init__(self, radius):
        """
        Circleインスタンスを作成する。

        Args:
            radius (float): 円の半径
        """
        self.radius = radius

    def area(self):
        """
        円の面積を計算する。

        Returns:
            float: 円の面積
        """
        import math
        return math.pi * self.radius ** 2

クラス本体には Attributes: を使ってプロパティ（属性）を説明し、
各メソッドには通常の関数と同じように Args: や Returns: を使います。

---

💡 Docstringの中で使える追加要素

Docstringでは以下のような項目も必要に応じて追加できます。

項目名	使い方の例	内容
Examples:	実際の使用例を記載	>>> add(2, 3)
Notes:	注意点や補足	特殊なケースの説明など
Todo:	今後追加する機能など	機能改善メモなどに便利

これらは必須ではありませんが、チーム開発やライブラリ公開の際に重宝します！

---

6. VS Code・PyCharmでの自動生成の活用法

「Docstringって便利そうだけど、毎回手で書くのはちょっと面倒かも…」
そう感じた方もいるかもしれません。でもご安心を！

実は、Python向けのエディタにはDocstringを自動生成してくれる機能があるんです。
この章では、代表的な開発ツール「VS Code」と「PyCharm」でのDocstring自動生成方法を紹介します。

---

💻 VS CodeでDocstringを自動生成する方法

🔧 必要な準備

まず、**拡張機能「Python Docstring Generator」**をインストールしましょう。

1. サイドバーから「拡張機能（四角いアイコン）」をクリック
2. 「Python Docstring Generator」で検索
3. インストールボタンをクリック

この拡張機能は、GoogleスタイルのDocstringを自動生成してくれます。

✅ 使い方

関数定義の行にカーソルを合わせて、

• Windows：Alt + Shift + 2
• macOS：Option + Shift + 2

を押すだけで、関数の引数や戻り値の情報をもとに、テンプレートが一瞬で入力されます！

def add(a, b):
    """
    Summary.

    Args:
        a (TYPE): Description
        b (TYPE): Description

    Returns:
        TYPE: Description
    """
    return a + b

あとは TYPE や Description の部分を自分で埋めるだけ。
入力の手間がぐっと減りますよ！

---

🧠 PyCharmでのDocstring自動補完

PyCharmでは、標準機能としてDocstringを自動補完してくれます。

🛠 デフォルトの設定（reStructuredTextスタイル）

関数の上で """ を入力して Enter を押すだけで、以下のようにテンプレートが出てきます：

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

    :param a: 
    :type a: 
    :param b: 
    :type b: 
    :return: 
    :rtype: 
    """

⚙ Googleスタイルに変更したい場合

1. メニューの「Settings（設定）」または「Preferences」を開く
2. 「Tools」→「Python Integrated Tools」へ
3. 「Docstring format」で「Google」を選択
4. OKをクリックして保存

こうすれば、以降の自動生成はGoogleスタイルに切り替わります！

---

7. Docstringを書くタイミングと注意点

Docstring（ドッグストリング）はとても便利な機能ですが、
「どのタイミングで書くのがベスト？」
「書きすぎたり、逆に少なすぎたりしても大丈夫？」
といった疑問を持つ方も多いと思います。

ここでは、Docstringを効果的に活用するためのコツを紹介します！

---

⏰ 書くベストなタイミングは「実装が落ち着いた後」

Docstringは、関数やクラスの仕様（何をするか）が決まってから書くのが理想的です。

• ✖ コーディング前：まだ設計が曖昧だと、あとで書き直しになることが多い
• ✖ コーディング中：処理内容が変わると、説明も都度変更が必要になる
• ✔ コーディング後：完成した関数に沿って、正確で簡潔な説明が書ける

コードがある程度完成してから、落ち着いて説明を書くことで、読みやすく正確なDocstringが作れます。

---

⚠️ よくある注意点・失敗例

❌ 説明が曖昧 or 足りない

def process(data):
    """処理する関数。"""

このような説明だと、「何をどう処理するのか」がわかりません。
誰が見てもわかるように、具体的に書くことが大切です。

❌ 説明と実際の動作がずれている

def multiply(a, b):
    """
    2つの数値を加算する。
    """
    return a * b

↑ これは「掛け算しているのに、説明では加算と書いてある」という間違い。
Docstringを書いた後にコードを変えたときは、説明文の更新も忘れずに！

---

✅ Docstringを省略してもいいケース

実は、すべての関数に必ずDocstringを書く必要はありません。

以下のような場合は、省略してもOKです。

• 処理が明確すぎる場合

def clear_list():
    """リストを空にする。"""  ← この程度なら、Docstringなしでも十分伝わる

• 一時的なスクリプト・試験的な関数

学習中や検証用の関数で、他の人と共有する予定がないなら省略しても問題ありません。

---

8. まとめ｜Docstringで未来の自分と他人にやさしいコードを

Docstring（ドッグストリング）は、Pythonプログラムにおける説明書のような存在です。

関数・クラス・モジュールの冒頭に説明文を記載するだけで、
誰かがそのコードを使うとき、または自分が後で見返すときの理解がグッと楽になります。

---

✨ Docstringのポイントをおさらい

✅ 三重のダブルクォート """ で囲んで記述
✅ 関数・クラス・モジュールそれぞれに対応
✅ Googleスタイル or reStructuredTextスタイル を使って読みやすく
✅ VS CodeやPyCharmでは自動生成機能が使えて便利
✅ 書くタイミングは実装後がベスト！
✅ 具体的に・ズレなく・必要な範囲だけを書くのがコツ

---

Docstringを書くことは、未来の自分に優しくすることでもあり、他の人とコードを共有するためのマナーでもあります。

「これは面倒な作業」ではなく、「将来のトラブルを防ぐ投資」だと思って、ぜひ習慣にしてみてくださいね。

---

🧩 あわせて読みたい

Docstringに関連する知識を深めたい方は、以下の記事もおすすめです！

• 🔗 【Python入門9】関数の使い方をやさしく解説｜引数と戻り値を図解付きで理解しよう
  関数にDocstringを付けるなら、関数の仕組み自体も理解しておくとさらに安心！
• 🔗 初心者でもすぐわかる！Pythonのクラス入門ガイド｜オブジェクト指向をやさしく解説
  クラスのDocstringを書くときに知っておきたい、クラスとインスタンスの基本を解説。
• 🔗【Python入門】デコレーターの使い方と仕組みを初心者向けにやさしく解説！
  Docstringにも関係のある「関数を操作する関数」であるデコレーターもチェック！

---

よくある質問（Q&A）