Python docstringとは？関数の説明を書く基本的な方法
Pythonのdocstringの基本的な使い方から応用例まで解説。関数やクラスの説明を適切に書く方法を初心者向けに説明します。
Python docstringとは？関数の説明を書く基本的な方法
自分で書いた関数の使い方を忘れた経験はありませんか？
みなさん、Pythonでプログラミングをしているとき、こんな経験をしたことはありませんか？
「数ヶ月前に書いた関数の使い方が分からない」 「他の人が書いたコードを読むのに時間がかかる」 「引数に何を渡せばいいか忘れてしまった」
実は、Pythonのdocstringを使うことで、関数やクラスの説明を適切に記述できるんです。
この記事では、Pythonのdocstringの基本的な使い方から実践的な応用例まで、初心者にも分かりやすく解説します。 具体的なコード例とともに、段階的に理解できるよう丁寧に説明しますね！
docstringって何？基本概念から理解しよう
docstringは、Pythonにおけるドキュメンテーション文字列のことです。
関数、クラス、モジュールの説明を記述するための特別な文字列で、コードの直後に三重クォート（"""）で囲んで記述します。
通常のコメントとの違い
通常のコメントとは異なり、docstringは実行時にもアクセス可能です。 ヘルプ機能やドキュメント生成ツールでも活用できます。
def greet(name): """ 指定された名前で挨拶を行う関数 Args: name (str): 挨拶する相手の名前 Returns: str: 挨拶メッセージ """ return f"こんにちは、{name}さん！"
# docstringを確認print(greet.__doc__)このコードを実行すると、greet関数のdocstringが表示されます。
__doc__属性を使うことで、関数の説明をプログラムから取得できるんです。
docstringの基本的な書き方をマスターしよう
最も基本的な記述方法
docstringは関数やクラスの定義の直後に記述します。
def calculate_area(radius): """円の面積を計算する関数""" import math return math.pi * (radius ** 2)
class Person: """人を表すクラス""" def __init__(self, name, age): """ Personクラスのコンストラクタ Args: name (str): 名前 age (int): 年齢 """ self.name = name self.age = age関数の場合はdef文の直後に、クラスの場合はclass文の直後に記述します。
一行docstringと複数行docstring
一行docstringでシンプルに
簡潔な説明の場合は一行で記述できます。
def add(a, b): """2つの数値を加算する""" return a + b
def get_current_time(): """現在の時刻を取得する""" from datetime import datetime return datetime.now()一行docstringは、関数の目的が明確で簡単な場合に適しています。
何をする関数なのかが一目で分かるのが良いですね。
複数行docstringで詳しく説明
詳細な説明が必要な場合は複数行で記述します。
def process_data(data, operation="sum"): """ データに対して指定された操作を実行する この関数は数値のリストを受け取り、指定された操作を実行します。 サポートされている操作: sum, average, max, min Args: data (list): 処理するデータのリスト operation (str): 実行する操作（デフォルト: "sum"） Returns: float: 計算結果 Raises: ValueError: 無効な操作が指定された場合 TypeError: データが数値でない場合 Examples: >>> process_data([1, 2, 3, 4, 5]) 15 >>> process_data([1, 2, 3, 4, 5], "average") 3.0 """ if not all(isinstance(x, (int, float)) for x in data): raise TypeError("データは数値である必要があります") if operation == "sum": return sum(data) elif operation == "average": return sum(data) / len(data) elif operation == "max": return max(data) elif operation == "min": return min(data) else: raise ValueError(f"無効な操作: {operation}")このコードでは、関数の詳しい説明、引数、戻り値、例外、使用例までを記述しています。
複数行docstringを使うことで、関数の使い方が非常に分かりやすくなります。
人気のdocstringフォーマットを覚えよう
Google Styleで読みやすく書こう
Google Styleは読みやすく、一般的に使われているフォーマットです。
def calculate_discount(price, discount_rate, member_type="regular"): """ 価格に対して割引を適用する Args: price (float): 元の価格 discount_rate (float): 割引率（0.0-1.0） member_type (str): 会員種別（"regular" or "premium"） Returns: float: 割引後の価格 Raises: ValueError: 価格が負の値の場合 ValueError: 割引率が0.0-1.0の範囲外の場合 """ if price < 0: raise ValueError("価格は0以上である必要があります") if not 0.0 <= discount_rate <= 1.0: raise ValueError("割引率は0.0-1.0の範囲である必要があります") base_discount = price * discount_rate if member_type == "premium": additional_discount = price * 0.05 # プレミアム会員は追加5%割引 return price - base_discount - additional_discount else: return price - base_discountGoogle Styleでは、Args、Returns、Raisesなどのセクションで情報を整理します。
各引数の型と説明が明確に記述されているため、使い方が分かりやすいです。
NumPy Styleも知っておこう
NumPy Styleは科学計算分野でよく使われます。
def linear_regression(x, y): """ 線形回帰を実行する Parameters ---------- x : array_like 独立変数のデータ y : array_like 従属変数のデータ Returns ------- tuple (slope, intercept) の形式で回帰係数を返す Notes ----- 最小二乗法を使用して線形回帰を実行します。 Examples -------- >>> x = [1, 2, 3, 4, 5] >>> y = [2, 4, 6, 8, 10] >>> slope, intercept = linear_regression(x, y) >>> print(f"傾き: {slope}, 切片: {intercept}") """ n = len(x) sum_x = sum(x) sum_y = sum(y) sum_xy = sum(x[i] * y[i] for i in range(n)) sum_x2 = sum(x[i] ** 2 for i in range(n)) slope = (n * sum_xy - sum_x * sum_y) / (n * sum_x2 - sum_x ** 2) intercept = (sum_y - slope * sum_x) / n return slope, interceptNumPy Styleでは、Parameters、Returns、Notes、Examplesなどのセクションを使います。
科学計算のライブラリでよく見かけるフォーマットですね。
クラスのdocstringを書いてみよう
クラス全体の説明を詳しく書こう
クラスのdocstringでは、クラスの目的と使い方を説明します。
class BankAccount: """ 銀行口座を表すクラス このクラスは銀行口座の基本的な操作（預金、引き出し、残高確認）を提供します。 Attributes: account_number (str): 口座番号 balance (float): 残高 owner (str): 口座名義人 Examples: >>> account = BankAccount("12345", "田中太郎", 1000) >>> account.deposit(500) >>> print(account.get_balance()) 1500.0 """ def __init__(self, account_number, owner, initial_balance=0): """ BankAccountクラスのコンストラクタ Args: account_number (str): 口座番号 owner (str): 口座名義人 initial_balance (float): 初期残高（デフォルト: 0） """ self.account_number = account_number self.owner = owner self.balance = initial_balance def deposit(self, amount): """ 指定された金額を預金する Args: amount (float): 預金額 Raises: ValueError: 預金額が0以下の場合 """ if amount <= 0: raise ValueError("預金額は0より大きい必要があります") self.balance += amount def withdraw(self, amount): """ 指定された金額を引き出す Args: amount (float): 引き出し額 Returns: bool: 引き出しが成功した場合はTrue、失敗した場合はFalse Raises: ValueError: 引き出し額が0以下の場合 """ if amount <= 0: raise ValueError("引き出し額は0より大きい必要があります") if amount > self.balance: return False self.balance -= amount return True def get_balance(self): """ 現在の残高を取得する Returns: float: 現在の残高 """ return self.balanceこのクラスでは、各メソッドにも詳細なdocstringを記述しています。
クラスの使い方と各メソッドの役割が明確に分かりますね。
モジュールのdocstringも重要です
ファイルの先頭に書くモジュール説明
モジュール（Pythonファイル）の先頭にもdocstringを書けます。
"""数学的計算を行うユーティリティモジュール
このモジュールは基本的な数学的計算を行う関数を提供します。統計計算、幾何学計算、金融計算などが含まれています。
Author: 開発者名Version: 1.0.0Created: 2024-01-01"""
import mathfrom typing import List, Union
def calculate_statistics(data: List[Union[int, float]]) -> dict: """ データの基本統計量を計算する Args: data: 数値のリスト Returns: dict: 統計量の辞書（mean, median, std_dev, count） """ if not data: return {} # 平均値 mean = sum(data) / len(data) # 中央値 sorted_data = sorted(data) n = len(sorted_data) if n % 2 == 0: median = (sorted_data[n//2 - 1] + sorted_data[n//2]) / 2 else: median = sorted_data[n//2] # 標準偏差 variance = sum((x - mean) ** 2 for x in data) / len(data) std_dev = math.sqrt(variance) return { "mean": mean, "median": median, "std_dev": std_dev, "count": len(data) }モジュールdocstringでは、ファイル全体の目的や作成者、バージョン情報を記述できます。
他の開発者がファイルを見たときに、何のためのモジュールなのかすぐに分かります。
docstringを実際に活用してみよう
help()関数で確認
Pythonの組み込みhelp()関数でdocstringを確認できます。
def fibonacci(n): """ フィボナッチ数列のn番目の値を計算する Args: n (int): 計算する項数（0以上） Returns: int: フィボナッチ数列のn番目の値 Examples: >>> fibonacci(0) 0 >>> fibonacci(1) 1 >>> fibonacci(10) 55 """ if n <= 0: return 0 elif n == 1: return 1 else: return fibonacci(n-1) + fibonacci(n-2)
# ヘルプを表示help(fibonacci)このコードを実行すると、fibonacci関数の詳しい説明が表示されます。
help()関数は、対話型Python環境で非常に便利です。
__doc__属性で直接アクセス
__doc__属性を使って、docstringに直接アクセスすることもできます。
# docstringに直接アクセスprint(fibonacci.__doc__)
# クラスのdocstringprint(BankAccount.__doc__)
# メソッドのdocstringprint(BankAccount.deposit.__doc__)プログラムの中でdocstringを取得して、動的にヘルプを表示することも可能です。
良いdocstringを書くコツ
理想的なdocstringの例
def validate_email(email): """ メールアドレスの形式を検証する 基本的なメールアドレスの形式チェックを行います。 完全なRFC準拠ではありませんが、一般的な形式を検証します。 Args: email (str): 検証するメールアドレス Returns: bool: 有効な形式の場合はTrue、無効な場合はFalse Examples: >>> validate_email("test@example.com") True >>> validate_email("invalid-email") False Note: この関数は基本的な検証のみを行います。 本格的な検証には専用のライブラリを使用することを推奨します。 """ import re pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' return re.match(pattern, email) is not Noneこのdocstringでは、関数の目的、制限事項、使用例、注意点まで記述されています。
避けるべきdocstringの例
以下のような書き方は避けましょう。
# 悪い例1: 曖昧な説明def process(data): """データを処理する""" # 何を処理するか不明 return data.upper()
# 悪い例2: 引数の説明不足def calculate(x, y, z): """計算を行う""" # 引数の説明がない return x + y * z
# 良い例: 明確で詳細な説明def format_name(first_name, last_name, middle_initial=None): """ 名前を標準的な形式でフォーマットする Args: first_name (str): 名 last_name (str): 姓 middle_initial (str, optional): ミドルネームの頭文字 Returns: str: フォーマット済みの氏名 Examples: >>> format_name("太郎", "田中") "田中 太郎" >>> format_name("太郎", "田中", "T") "田中 T. 太郎" """ if middle_initial: return f"{last_name} {middle_initial}. {first_name}" else: return f"{last_name} {first_name}"良いdocstringの特徴：
- 関数の目的が明確
- 引数と戻り値の説明が詳しい
- 具体的な使用例がある
- 制限事項や注意点も記述
高度なdocstring活用法
動的なdocstring生成
実行時にdocstringを変更することも可能です。
def create_dynamic_function(operation_name): """動的に関数を作成し、docstringを設定する""" def dynamic_function(x, y): if operation_name == "add": return x + y elif operation_name == "multiply": return x * y # 動的にdocstringを設定 dynamic_function.__doc__ = f""" {operation_name}演算を実行する動的関数 Args: x (float): 第1オペランド y (float): 第2オペランド Returns: float: {operation_name}の結果 """ return dynamic_function
# 使用例add_func = create_dynamic_function("add")print(add_func.__doc__)このコードでは、実行時に関数のdocstringを動的に生成しています。
関数の動作に応じて説明を変更できるのが便利ですね。
まとめ
Pythonのdocstringは、コードの可読性と保守性を向上させるための重要な機能です。
この記事で学んだ重要なポイント：
- docstringは三重クォートで囲んだドキュメンテーション文字列
- Google Style、NumPy Styleなどのフォーマットがある
- 関数、クラス、モジュールに適用可能
- help()関数や__doc__属性でアクセス可能
- 明確で詳細な説明が良いdocstringの条件
良いドキュメントは、開発効率を向上させ、チーム開発を円滑にします。
docstringを使いこなすことで、より理解しやすく保守性の高いPythonコードを書けるようになります。 ぜひ実際のプロジェクトで活用してみてください！