Python Docstringの書き方：コードを分かりやすくする秘訣
Python開発者の皆さん、コードの可読性を高め、メンテナンスを楽にしたいと思いませんか？その鍵を握るのが**Docstring（ドキュメント文字列）**です。Docstringは、関数、クラス、モジュールなどの説明を記述するための重要な要素で、コードの理解を深めるだけでなく、自動ドキュメント生成ツールにも活用されます。
Docstringとは？
Docstringは、Pythonコード内で特定のオブジェクト（モジュール、クラス、関数、メソッド）の直後に記述される文字列リテラルです。通常のコメントとは異なり、実行時にアクセス可能であり、help()関数やIDEのツールチップで表示されるため、コードの利用者がその機能や使い方をすぐに理解するのに役立ちます。
Docstringは通常、三重引用符（"""または'''）で囲んで記述します。
Docstringの基本的な書き方
Docstringには、大きく分けて2つの種類があります。
1行Docstring
機能がシンプルで説明が短い場合に適しています。開始と終了の引用符と同じ行に記述します。
def add(a, b):
"""2つの数値を加算して返します。"""
return a + b
複数行Docstring
より詳細な説明が必要な場合に利用します。通常、以下の要素を含みます。
概要行（Summary Line）: オブジェクトの機能の簡潔な要約を1行で記述します。
空白行: 概要行とそれ以降の詳細な説明を区切ります。
詳細説明: 機能、引数、戻り値、例外、使用例などを記述します。
def multiply(a, b):
"""
2つの数値を乗算して結果を返します。
Parameters:
a (int): 1つ目の数値
b (int): 2つ目の数値
Returns:
int: 乗算された結果
"""
return a * b
Docstringを書くべき場所
Docstringは以下の場所に記述することが推奨されています。
モジュール
モジュール全体の目的や内容を説明します。
"""
このモジュールは数値計算に関連するユーティリティ関数を提供します。
"""
def add(a, b):
"""2つの数値を加算します。"""
return a + b
クラス
クラスの目的や属性、メソッドの概要を説明します。
class Calculator:
"""
基本的な算術演算を行うための計算機クラスです。
"""
def __init__(self):
"""Calculatorオブジェクトを初期化します。"""
pass
def divide(self, a, b):
"""
2つの数値を割り算して結果を返します。
bが0の場合はZeroDivisionErrorを送出します。
"""
if b == 0:
raise ZeroDivisionError("0で割ることはできません。")
return a / b
関数とメソッド
関数やメソッドの機能、引数、戻り値、発生しうる例外などを説明します。
def greet(name):
"""
指定された名前で挨拶メッセージを生成します。
Parameters:
name (str): 挨拶する人の名前
Returns:
str: 挨拶メッセージ
"""
return f"こんにちは、{name}さん！"
Docstringのスタイルガイド
Pythonには公式のスタイルガイドであるPEP 257が存在します。これに従うことで、統一性のあるDocstringを書くことができます。
一般的な推奨事項
三重引用符を使用する:
"""Docstring"""1行Docstringの場合: 終了引用符を同じ行に置く。
複数行Docstringの場合:
最初の行はオブジェクトの簡潔な要約にする。
要約の後に空行を入れる。
詳細な説明はインデントなしで記述する。
パラメータ、戻り値、例外などは専用のセクションを設ける。
コマンド形式で記述する: 例：「値を返す」ではなく「値を返します」。
Docstringのフォーマット
Docstringの記述には、様々なフォーマットが利用されます。主要なものとしては以下の3つがあります。
1. reStructuredText (reST)
Sphinxなどのドキュメント生成ツールで広く使われています。
def example_reST(param1, param2):
"""
reStructuredText形式のDocstringの例。
:param param1: 1番目のパラメータ
:type param1: str
:param param2: 2番目のパラメータ
:type param2: int
:returns: 結合された文字列
:rtype: str
:raises ValueError: param2が負の場合
"""
if param2 < 0:
raise ValueError("param2は正の数でなければなりません。")
return f"{param1}-{param2}"
2. NumPy Style
科学計算ライブラリでよく見られます。
def example_numpy(param1, param2):
"""
NumPyスタイルのDocstringの例。
Parameters
----------
param1 : str
1番目のパラメータ
param2 : int
2番目のパラメータ
Returns
-------
str
結合された文字列
Raises
------
ValueError
param2が負の場合
"""
if param2 < 0:
raise ValueError("param2は正の数でなければなりません。")
return f"{param1}-{param2}"
3. Google Style
Googleが推奨するスタイルです。
def example_google(param1, param2):
"""
GoogleスタイルのDocstringの例。
Args:
param1 (str): 1番目のパラメータ
param2 (int): 2番目のパラメータ
Returns:
str: 結合された文字列
Raises:
ValueError: param2が負の場合
"""
if param2 < 0:
raise ValueError("param2は正の数でなければなりません。")
return f"{param1}-{param2}"
どのスタイルを採用するかはプロジェクトやチームの方針によりますが、一貫性を持たせることが重要です。
Docstringの重要性
Docstringは単なるコメントではありません。
可読性の向上: コードの目的や使い方を瞬時に理解できます。
メンテナンスの容易さ: 後からコードを修正する際に、動作を思い出す手間が省けます。
共同開発の効率化: チームメンバーがコードを共有し、理解するのに役立ちます。
自動ドキュメント生成: Sphinxなどのツールを使えば、Docstringからプロフェッショナルなドキュメントを自動生成できます。
良いDocstringは、コードそのものと同じくらい重要です。今日からあなたのPythonコードにDocstringを記述して、より良い開発体験を送りましょう！
■プロンプトだけでオリジナルアプリを開発・公開してみた！！
■AI時代の第一歩！「AI駆動開発コース」はじめました！
テックジム東京本校で先行開始。
■テックジム東京本校
「武田塾」のプログラミング版といえば「テックジム」。
講義動画なし、教科書なし。「進捗管理とコーチング」で効率学習。
より早く、より安く、しかも対面型のプログラミングスクールです。
＜短期講習＞5日で5万円の「Pythonミニキャンプ」開催中。
＜月1開催＞放送作家による映像ディレクター養成講座
＜オンライン無料＞ゼロから始めるPython爆速講座
