1. 👋 はじめに

Pythonのコードを読んでいると、関数の先頭にこんな """...""" を見かけませんか？

def greet(name):
    """あいさつ文を返す。"""
    return f"こんにちは、{name}さん！"

「この三重クォートの文、# のコメントと何が違うの？」
「そもそも書く意味あるの？飾り？」

初心者がまず引っかかるポイントです。実はこれ docstring（ドックストリング） という、コメントとは役割がまったく違う仕組みなんです。

この記事を読み終わるころには、こうなっています👇

✅ docstringとコメントの違いを仕組みで説明できる
✅ __doc__ と help() でdocstringを取り出せる
✅ どこに（関数・クラス・モジュール）書くか分かる
✅ PEP 257に沿った基本の書き方が身につく

📌 docstringの中身の書き方（Google/NumPy/reSTスタイル）は、次回のスタイル編でじっくり比較します。まずは「docstringとは何か」を固めましょう。

2. 🤔 docstringとは？

docstring＝モジュール・関数・クラス・メソッドの先頭に書く"説明文字列" です。

一言でいうと 「そのオブジェクトの取扱説明書」。ポイントは2つです。

場所：def や class、ファイルのいちばん先頭に書く
正体：ただの文字列リテラル（"""..."""）だが、Pythonが特別扱いして __doc__ という属性に自動で保存してくれる

def greet(name):
    """あいさつ文を返す。"""   # ← これがdocstring
    return f"こんにちは、{name}さん！"

この「__doc__に保存される」というのが、次に説明するコメントとの決定的な違いです。

3. 🔍 コメントとの違い【この記事の核】

見た目は似ていますが、両者はまったくの別物です。まず結論の対比表から👇

	`#` コメント	docstring
書き方	`# メモ`	`"""説明"""`（三重クォート）
書く場所	どこでも	モジュール/関数/クラスの先頭
実行時	完全に無視される	`__doc__` に保存される
取り出し	できない（消える）	`obj.__doc__` / `help(obj)`
誰のため	書いた人・読む人（コードの補足）	使う人・ツール（外向きの説明）
主な用途	「なぜこう書いたか」のメモ	「これは何をするか」の説明書

🍱 例えるなら「付箋」と「商品ラベル」

# コメント＝付箋📝：作った本人が内部に貼るメモ。箱を開けた人（コードを読む人）だけが見る。実行時には剥がれて消える。
docstring＝商品ラベル🏷️：箱の外に貼る公式な説明。中を開けなくても（help() で）読める。ツールも機械的に読み取れる。

💡 決定的な違いは「残るか・消えるか」

# コメントは実行時にただ無視されます。一方 docstring は __doc__ に残る。この差を、次のセクションで実際に目で確かめましょう👀

4. 🧪 実際に確認してみる（実況）

「保存される」って本当？手を動かして確かめます。

① 関数のdocstringを取り出す

こんな関数を demo.py に用意します。

def greet(name: str, formal: bool = False) -> str:
    """あいさつ文を組み立てて返す。

    相手の名前を受け取り、丁寧・カジュアルを切り替えて
    あいさつ文字列を生成する。

    Args:
        name (str): あいさつを向ける相手の名前。
        formal (bool): Trueなら丁寧な表現、Falseならカジュアルな表現。

    Returns:
        str: 生成したあいさつ文。
    """
    if formal:
        return f"こんにちは、{name}様。"
    return f"やあ、{name}さん！"

関数.__doc__ でdocstringを取り出せます。

>>> import demo
>>> print(demo.greet.__doc__)
あいさつ文を組み立てて返す。

    相手の名前を受け取り、丁寧・カジュアルを切り替えて
    あいさつ文字列を生成する。

    Args:
        name (str): あいさつを向ける相手の名前。
        formal (bool): Trueなら丁寧な表現、Falseならカジュアルな表現。

    Returns:
        str: 生成したあいさつ文。

ちゃんと文字列として保存されていました！🎉

② `help()` で"説明書"として表示する

さらに便利なのが help()。docstringを整形して、関数の使い方として見せてくれます。

>>> help(demo.greet)
Help on function greet in module demo:

greet(name: str, formal: bool = False) -> str
    あいさつ文を組み立てて返す。

    相手の名前を受け取り、丁寧・カジュアルを切り替えて
    あいさつ文字列を生成する。

    Args:
        name (str): あいさつを向ける相手の名前。
        formal (bool): Trueなら丁寧な表現、Falseならカジュアルな表現。

    Returns:
        str: 生成したあいさつ文。

関数のシグネチャ（引数）と一緒に、docstringが説明として表示されました。あなたが help(print) や help(list) を打ったときに出てくるあの説明も、実はdocstringなんです。

③ 対して、コメントは…？

同じ内容をコメントで書いた関数を見てみましょう。

def no_doc():
    # これはコメント。docstringではない。
    return 1

__doc__ を覗くと…👇

# repr()は「値を、あいまいさなく表示する」ための関数
>>> print(repr(no_doc.__doc__))
None

None。何も残っていません。 help() を打っても説明は出ず、関数の形だけが表示されます。

>>> help(no_doc)
Help on function no_doc in module __main__:

no_doc()

これが「消えるコメント」と「残るdocstring」の決定的な違いです。コメントはツールから見えず、docstringは見える——この一点が、docstringを書く最大の理由になります💡

5. 📍docstringを書く「場所」4種

docstringは4か所に書けます。すべて その定義の直後（先頭） に置くのがルールです。

1. モジュール（ファイルの先頭）

"""あいさつ機能を提供するサンプルモジュール。

このモジュールの目的や使い方をここに書く。
"""

ファイルの1行目（インポート文より前）に書きます。import demo してから demo.__doc__ で読めます。

2. 関数

def greet(name):
    """あいさつ文を返す。"""
    return f"こんにちは、{name}さん！"

3. クラス

class Circle:
    """円を表すクラス。"""

4. メソッド（クラス内の関数）

class Circle:
    """円を表すクラス。"""

    def area(self) -> float:
        """円の面積を返す。"""
        return 3.14159

それぞれ Circle.__doc__、Circle.area.__doc__ で個別に取り出せます。「説明したい単位ごとに1つ」 と覚えればOKです👌

6. 📏 PEP 257：docstringの基本ルール

docstringには PEP 257 という公式の指針があります。細かいですが、初心者が押さえるべきは次の5つだけです。

① 三重ダブルクォート `"""` を使う

1行でも """..."""（三重ダブルクォート）で書くのが公式推奨です。'...' や "..." でも動きますが、揃えましょう。

② 1行目は「短い要約」にする

最初の行は、その関数が何をするかを1文で要約します。詳細はその後に書きます。

③ 1行 vs 複数行を使い分ける

1行docstring（シンプルな処理）は、開き・閉じクォートを同じ行に置きます。

def add(a, b):
    """2つの数の和を返す。"""
    return a + b

複数行docstringは「要約 → 空行 → 詳細」の順。閉じ """ は独立した行に置きます。

def add(a, b):
    """2つの数の和を返す。

    ここに補足の説明を書く。
    """
    return a + b

④ 要約は「命令形」で書く（英語の慣習）

PEP 257は英語で "Return the sum."（命令形）を推奨しています。"Returns the sum." ではなく "Return ..."。日本語なら「〜を返す。」で自然に書けばOKです。

⑤ 末尾はピリオド（句点）で締める

要約は文として、. や 。 で終えます。

💡 PEP 257は「どこに・どう置くか」の土台ルール。**「Args や Returns をどう並べるか」という中身の様式は、Google/NumPy などの"スタイル"**で決まります。それは次回のスタイル編で！

7. ✅ 良い例・悪い例

🙅 悪い例：コメントで済ませる／中身がない

def calc(a, b):
    # aとbを計算する
    return a * b - a

「計算する」では何をするか分からず、コメントなのでツールからも見えません。

🙆 良い例：docstringで「何をする・何を受け取り・何を返すか」

def calc_discount(price: int, rate: float) -> int:
    """割引後の価格を計算して返す。

    Args:
        price (int): 元の価格（円）。
        rate (float): 割引率（0.0〜1.0）。

    Returns:
        int: 割引後の価格（円、小数切り捨て）。
    """
    # 割引額を引いて整数に丸める
    return int(price * (1 - rate))

💡 コメントとdocstringは「併用」が正解

対立するものではありません。役割で使い分けます。

docstring：この関数は「何をするか」（外向きの説明）
# コメント：この行は「なぜこう書いたか」（内部の補足）

上の良い例でも、docstringで全体を説明しつつ、# 割引額を引いて… というコメントで実装の意図を補っています。この組み合わせが読みやすいコードの基本です👍

8. 🎯 まとめ

ポイント	内容
📝 docstringとは	モジュール/関数/クラスの先頭に書く"説明文字列"
🏷️ コメントとの違い	コメントは実行時に消える／docstringは `__doc__` に残る
🔍 取り出し方	`obj.__doc__` または `help(obj)`
📍 書く場所	モジュール・関数・クラス・メソッドの先頭
📏 PEP 257	`"""` を使う・1行目は要約・末尾は句点
🤝 使い分け	docstring＝「何をするか」／コメント＝「なぜこう書いたか」

docstringは「飾り」ではなく、help() やIDE、ドキュメント生成ツールが読み取る"公式の説明書" です。書いておくと、未来の自分もチームメンバーも、コードの中を読まずに使い方が分かります🌟

まずは自分の関数に1行docstringを足すところから始めてみてください。help(あなたの関数) で表示された瞬間、ちょっと感動しますよ😊

💬 質問や感想があれば、コメント欄でお気軽にどうぞ!
👍 役に立ったら、いいね&ストックをお願いします!
🎓 ここまで読んでくださって、本当にありがとうございました!

🔗 シリーズ記事

【第一回】docstringとは？コメントとの違い（この記事）
【第二回】docstringの書き方3スタイル比較（近日公開）— Googleを軸にNumPy・reStructuredTextを比較