はじめに
Pythonで関数やクラスを書くとき、つい**「説明はコメントで済ませよう」**となっていませんか？
でも、Pythonには**Docstring（ドックストリング）**という正式な「説明の書き方」が用意されており、しっかり活用することで以下のようなメリットがあります：
- ✅ コードの可読性・再利用性アップ
- ✅ 自動ドキュメント生成に対応
- ✅ チーム開発や自分の将来の自分が助かる！
さらに、VS Codeと拡張機能を使えば、Docstringの作成が超ラクになります。
この記事では、Docstringの基礎から実践方法、さらに練習用サンプルコードまでまとめて紹介します！
📖 Docstringとは？
Docstringは、Pythonの関数・クラス・モジュールの説明を記述する特別な文字列です。
"""三重クォート"""で囲んで書き、関数やクラスの直後に記述します。
🔰 例：関数にDocstringを書く
def greet(name):
"""
指定された名前の人に挨拶を返します。
Parameters:
name (str): 挨拶する相手の名前
Returns:
str: 挨拶文
"""
return f"こんにちは、{name}さん！"
🔍 Docstringの確認方法
Docstringは、Pythonのhelp()関数を使って簡単に確認できます。
help(greet)
実行結果：
Help on function greet in module __main__:
greet(name)
指定された名前の人に挨拶を返します。
Parameters:
name (str): 挨拶する相手の名前
Returns:
str: 挨拶文
📝 Docstringの書き方とスタイル
PythonにはDocstringに関する公式ガイドラインPEP 257があります。
以下のようなルールを守ると、他の人にも優しいコードになります。
✅ 書き方のポイント
- トリプルダブルクォート（
""" """）を使用 - 最初の行は簡潔な概要（1行で）
- 2行目は空行を入れる
- 詳細説明や引数、戻り値の情報を書く
📘 Docstringのスタイル例
🟦 Googleスタイル
def add(a, b):
"""
2つの数値を加算します。
Args:
a (int): 最初の数値
b (int): 2番目の数値
Returns:
int: 加算結果
"""
return a + b
🟩 NumPyスタイル
def subtract(a, b):
"""
2つの数値を減算します。
Parameters
----------
a : int
最初の数値
b : int
減算する数値
Returns
-------
int
減算結果
"""
return a - b
💻 VS CodeでDocstringを効率よく書く！
🧩 1. 拡張機能「autoDocstring」の導入
- VS Codeの拡張機能メニューを開く
-
autoDocstringを検索 -
autoDocstring - Python Docstring Generatorをインストール！
⚙️ 2. 自動Docstringの使い方
✨ ショートカットで一発生成
関数にカーソルを合わせて
👉 Windows/Linux: Alt + Shift + 2
👉 macOS: Option + Shift + 2
⌨️ Docstringスタイルの変更
NumPyスタイルなどに変えたい場合は、設定で変更可能：
"autoDocstring.docstringFormat": "numpy"
VS Codeの「設定 (JSON)」で追加してください。
📄 3. 試してみよう！Docstring練習用サンプルコード
以下のコードを sample_docstring.py として保存すれば、
モジュール / クラス / 関数 にDocstringを書く練習が一気にできます！
適用前
# sample_docstring.py
class Calculator:
# 簡単な計算を行うクラス。
def __init__(self, name: str):
self.name = name
def add(self, a: float, b: float) -> float:
return a + b
def divide(self, a: float, b: float) -> float:
if b == 0:
raise ZeroDivisionError("0では割り算できません。")
return a / b
def greet(name: str) -> str:
return f"こんにちは、{name}さん！"
if __name__ == "__main__":
calc = Calculator("MyCalc")
print(calc.add(3, 5))
print(calc.divide(10, 2))
print(greet("Python"))
適用後
"""
sample_docstring.py
このモジュールは、Docstringの基本的な使い方を試すためのサンプルです。
"""
class Calculator:
"""
簡単な計算を行うクラス。
Attributes:
name (str): 計算機の名前
"""
def __init__(self, name: str):
"""
Calculatorクラスの初期化。
Args:
name (str): 計算機の名前
"""
self.name = name
def add(self, a: float, b: float) -> float:
"""
2つの数値を加算します。
Args:
a (float): 最初の数値
b (float): 2番目の数値
Returns:
float: 加算結果
"""
return a + b
def divide(self, a: float, b: float) -> float:
"""
2つの数値を除算します。
Args:
a (float): 割られる数
b (float): 割る数
Returns:
float: 除算結果
Raises:
ZeroDivisionError: bが0の場合
"""
if b == 0:
raise ZeroDivisionError("0では割り算できません。")
return a / b
def greet(name: str) -> str:
"""
名前を指定して挨拶メッセージを返します。
Args:
name (str): 挨拶する相手の名前
Returns:
str: 挨拶文
"""
return f"こんにちは、{name}さん！"
if __name__ == "__main__":
calc = Calculator("MyCalc")
print(calc.add(3, 5))
print(calc.divide(10, 2))
print(greet("Python"))
🧠 まとめ
| 項目 | 内容 |
|---|---|
| 📚 Docstringとは | 関数・クラス・モジュールの説明を書く公式な方法 |
| ✅ 書き方の基本 |
"""三重クォート"""、引数や戻り値を記述 |
| 💻 VS Code活用 |
autoDocstring拡張機能でラクに書ける |
| 🔧 カスタマイズ | Google / NumPy スタイルに変更可能 |
| 🧪 サンプルコード | 練習用コードで実践的に学べる |
✍️ あなたのコードにも、説明を添えてみませんか？
Docstringを書くことは、他人のためだけでなく未来の自分のための投資です。
今日から一緒に、「説明できるコード」を始めましょう！