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を比較