Python Docstringの書き方完全ガイド｜主要スタイルの比較と保守性を高める記述

本サイトのコンテンツは、生成AI＋人力で作成されている記事があります。 可能な限りのファクトチェックは行っておりますが、一部の情報が正確ではない可能性がありますので予めご了承ください。

「python docstring 書き方」を学びたいけれど、GoogleスタイルやNumPyスタイルなど種類が多くて迷っていませんか？適切なドキュメントは、自分やチームの保守性を劇的に高めます。本記事では、PEP 257の基本から主要スタイルの比較、自動生成ツールの活用法まで徹底解説します。

なお、Python全体のコーディング規約については、PEP 8の基本ガイドも併せて参照すると、より統一感のあるコードが書けるようになります。

この記事を読めば、初心者でも迷わず現場で役立つDocstringが書けるようになり、コードの品質を向上させられます。

記事のポイント

• PEP 257の基本に加え、GoogleやNumPy、reSTといった主要な記述スタイルの特徴とプロジェクトに最適な選び方が理解できます。
• 関数やクラスの引数・戻り値を明文化することで、自分だけでなく他人も読みやすい保守性の高いコードが書けるようになります。
• コメント（#）とDocstring（"""）の役割の違いを整理し、開発現場で迷わない適切な使い分けを習得できます。
• Sphinxなどの自動生成ツールやVS Codeの拡張機能を活用して、ドキュメント作成の工数を大幅に削減する手法が分かります。
• チーム開発に役立つチェックリストにより、プロジェクト全体で統一感のある高品質なドキュメント管理が実現します。

Python Docstringの書き方と主要な記述スタイル

Pythonの Docstring（ドキュメント文字列） は、コードの機能や使い方を説明するための重要な仕組みです。適切なDocstringを記述することで、自分自身の備忘録になるだけでなく、チーム開発におけるコードの可読性や保守性を大きく向上させることが期待できます。ここでは、公式の規約である PEP 257 の基本から、現場でよく使われる主要な記述スタイルまでを詳しく解説します。

PEP 257に準拠したDocstringの基本的な書き方

Pythonには PEP 257 というDocstringに関する公式のスタイルガイドが存在します。このガイドラインでは、Docstringを記述する際の基本的な作法が定義されています。

• トリプルクォート（"""）を使用する ：Docstringは、原則として3つのダブルクォートで囲みます。
• 1行目に要約を書く ：最初の行には、そのオブジェクトの役割を簡潔に記述します。
• 詳細が必要な場合は空行を挟む ：要約だけでは不十分な場合、1行の空行を挟んでから詳細な説明を記述します。
• 末尾のクォートは独立させることが推奨される ：PEP 257では一貫した整形を促す例として、複数行のDocstringでは閉じクォートを単独の行に置くことを推奨しています。必須ではありませんが、可読性のため広く用いられます。
• 要約行の書き方: 1行目の要約は、「何をするか」を言い切る形（「〜する」「〜を返す」など） で記述します。英語では命令形（Do this, Return that）が推奨されており、日本語では「〜の計算」のような名詞形ではなく、動作を明示する終止形（辞書形）で書くのが一般的です。
• 句点の徹底: 1行目の末尾は、英語ならピリオド、日本語なら句点（。）で終わらせることが推奨されています。
• 空行のルール: 複数行のDocstringでは、要約行と詳細説明の間に1行の空行を挟むのが推奨されています。

参考： PEP 257では、モジュール、関数、クラス、メソッドそれぞれに対して、何を記述すべきかの詳細なガイドラインも提供されています。詳しくは公式文書を参照してください。

1
def example_function():
2
    """関数の役割を1行で記述する。
3

4
    必要に応じて、ここに詳細な動作や
5
    注意点などを複数行で記述することが推奨されます。
6
    """
7
    pass

Googleスタイル・NumPyスタイル・reSTスタイルの特徴と違い

Docstringにはいくつかの代表的な記述スタイルがあります。プロジェクトの性質やチームの好みに合わせて選択されることが多いですが、主な3つのスタイルの特徴を比較してみましょう。

可読性が高く初心者にもおすすめなGoogleスタイル

Googleスタイル は、記述がシンプルで直感的に理解しやすいのが特徴です。 Args: や Returns: といった項目名を用いて情報を整理するため、初心者の方でも書きやすく、多くのモダンなプロジェクトで採用されています。

1
def divide(a: float, b: float) -> float:
2
    """2つの数値の商を計算する。
3

4
    Args:
5
        a (float): 分子となる数値。
6
        b (float): 分母となる数値。
7

8
    Returns:
9
        float: 計算された商。
10

11
    Raises:
12
        ZeroDivisionError: bが0の場合に発生。
13
    """
14
    return a / b

Googleスタイルでよく使われるセクション

科学計算やデータ分析分野で主流のNumPyスタイル

NumPyスタイル は、各項目の下にハイフン（---）を引いて区切りを作るなど、視覚的に構造が分かりやすい形式です。扱うパラメータが多いデータサイエンス系のライブラリ（pandasやscikit-learnなど）でよく見かけます。

1
def divide(a: float, b: float) -> float:
2
    """
3
    2つの数値の商を計算する。
4

5
    Parameters
6
    ----------
7
    a : float
8
        分子となる数値。
9
    b : float
10
        分母となる数値。
11

12
    Returns
13
    -------
14
    float
15
        計算された商。
16

17
    Raises
18
    ------
19
    ZeroDivisionError
20
        bが0の場合に発生。
21
    """
22
    return a / b

NumPyスタイルでよく使われるセクション

• 下線の長さ: 各セクションの見出し（Parametersなど）の下に引くハイフン（-）は、**「見出しの文字数と同じ長さ」**にするのがNumPy公式のルールです。
  • Parameters ならハイフン10個：----------
  • Returns ならハイフン7個：-------
  • 長さが足りないと、一部の解析ツールで正しく認識されない可能性があるため注意が必要です。

Python標準のSphinxと相性が良いreStructuredTextスタイル

reStructuredText（reST） は、Python公式ドキュメントで採用されている代表的な記法であり、Sphinxとの連携が標準的にサポートされています。Python言語仕様で「標準」と定められているわけではありませんが、実質的なデファクトスタンダードといえます。

1
def divide(a: float, b: float) -> float:
2
    """2つの数値の商を計算する。
3

4
    :param a: 分子となる数値。
5
    :type a: float
6
    :param b: 分母となる数値。
7
    :type b: float
8
    :returns: 計算された商。
9
    :rtype: float
10
    :raises ZeroDivisionError: bが0の場合に発生。
11
    """
12
    return a / b

reSTスタイルでよく使われるフィールド

関数・クラス・モジュール別の具体的な記述例

ここでは、最も利用頻度が高い Googleスタイル を例に、モジュール・関数・クラスの書き方を紹介します。

ファイル全体の役割を示すモジュールのDocstring

モジュールのDocstringは、ファイルの先頭（全てのインポート文より前）に記述します。そのファイルがどのような目的で作成され、どのような機能を提供するのかを記述します。

1
"""数学計算ユーティリティモジュール。
2

3
このモジュールは、面積計算や独自の数値変換などの
4
数学的な機能を提供します。
5
"""
6
import math

引数・戻り値・例外を明記する関数のDocstring

関数では、どのようなデータを受け取り、何を返すのかを明確にすることが重要です。

1
def calculate_area(width, height):
2
    """長方形の面積を計算する。
3

4
    Args:
5
        width (float): 幅。
6
        height (float): 高さ。
7

8
    Returns:
9
        float: 計算された面積。
10
    """
11
    return width * height

Tips: 型ヒント（Type Hints）との使い分け Python 3.5以降では（PEP 484）、def func(n: int) -> str:のようにコード自体に型を記述する「型ヒント」が推奨されています。そのため、現代的なDocstringでは型の詳細よりも「その引数が何を意味するのか（ビジネスロジック上の意味）」に注力して記述するのが一般的です。型情報はコードで表現し、Docstringではその引数の目的や制約を説明するという役割分担が理想的です。

型ヒントをすでに導入している場合、Docstringでの型記述には2つの考え方があります。

• DRY原則の重視: コード側に型が明記されているため、Docstring内では型を省略し、引数の「意味」や「制約」の説明に特化します。
• 可視性の重視: 一方で、IDEでホバーした際に説明と型が同時に見えるメリットを考慮し、あえてDocstring内にも型を重複させて記述するスタイルもあります。この場合、ツール（napoleonなど）を使用して同期を保つのが一般的です。

属性とメソッドの役割を整理するクラスのDocstring

クラスのDocstringでは、そのクラスが何を表すのかという概要に加え、 Attributes（属性） セクションでインスタンス変数の説明を行うことが一般的です。

1
class Rectangle:
2
    """長方形を表すクラス。
3

4
    Attributes:
5
        width (float): 幅。
6
        height (float): 高さ。
7
    """
8

9
    def __init__(self, width, height):
10
        self.width = width
11
        self.height = height

このように、適切なスタイルを選んで記述することで、コードの意図が明確になり、後からのメンテナンスがスムーズになる可能性が高まります。

固有のDocstring書き方

通常の関数以外にも、現代のPython開発で頻出するオブジェクトには固有の書き方があります。

• Dataclasses（データクラス）: 各フィールドの直下にトリプルクォートでDocstringを記述することで、フィールドごとの説明が可能です。
• Enum（列挙型）: Enumの各メンバーの直後にもDocstringを記述できます。これにより、各定数の意味を明確に定義できます。
• クラスのAttributesセクション: クラス全体のDocstringには Attributes セクションを設け、インスタンス変数の説明を記述します。一方で、コンストラクタの引数については、__init__ メソッド自身のDocstringに記述するのが一般的です。

PythonのDocstringに関するよくある疑問と解決策

PythonのDocstringを実際に書き始めると、「普通のコメントと何が違うのか？」「書いた内容をどう活用すればいいのか？」といった疑問が湧くことが少なくありません。ここでは、開発現場でよく寄せられる代表的な疑問について、実務的な視点で整理して解説します。

コメント（#）とDocstring（"""）の使い分けはどうすればいい？

Pythonには、ハッシュ記号（ # ）から始まる「コメント」と、トリプルクォート（ """ ）で囲む「Docstring」の2種類がありますが、これらは技術的にも目的的にも明確に役割が異なります。

技術的な違い：

• Docstring は実行時に __doc__ 属性として保持され、help() 関数やIDEのツールチップで参照可能です。
• コメント はPythonインタプリタによって解釈時に破棄され、実行時には存在しません。

目的の違い：

• Docstring は「そのコードを外部から使う人のため」に書き、APIの使い方を説明します。
• コメント は「そのコードを修正する開発者のため」に書き、実装の理由や背景を説明します。

Docstringは「そのコードを外部から使う人のため」 に書き、 コメントは「そのコードを修正する開発者のため」 に書くのが一般的です。

例えば、複雑なアルゴリズムの途中で「なぜこの計算式が必要なのか」を説明する場合は コメント を使用し、関数の「引数の型や戻り値の意味」を説明する場合は Docstring を使用するのが適切な使い分けと言えます。

Sphinxやpdocを活用してドキュメントを自動生成する方法

Docstringをルールに従って丁寧に記述する最大のメリットの一つは、ドキュメントの自動生成ツールを活用できる点にあります。これにより、ソースコードとドキュメントの乖離を防ぎ、常に最新の仕様書を維持しやすくなります。

代表的なツールには以下の2つがあります。

1. Sphinx（スフィンクス） Python公式ドキュメントでも採用されている、最も高機能なドキュメント生成ツールです。 reStructuredText（reST） スタイルを標準としていますが、拡張機能（napoleon）を追加することでGoogleスタイルやNumPyスタイルにも対応可能です。大規模なプロジェクトや、PDF形式での配布が必要な場合に適しているとされています。

2. pdoc 「設定よりも規約」を重視した、非常に軽量なツールです。特別な設定ファイルを用意しなくても、コマンド一つでモダンなデザインのHTMLドキュメントを生成できます。小中規模のプロジェクトや、手軽にブラウザで仕様を確認したい場合に非常に便利です。

1
pip install pdoc
2
pdoc my_module.py -o ./docs

このように、適切なツールを導入することで、記述した Docstring がそのままチーム共有用の技術ドキュメントとして資産化されるため、開発効率の向上が期待できるでしょう。

Docstringを書くだけでなく、その品質を維持するためのバリデーション（検証）が重要です。

• doctestによる実行例の検証: Docstring内に >>> を使った実行例（Examples）を記述しておくと、doctest モジュールを使用して、その例が実際に正しく動作するかを自動テストできます。
• 整合性チェック（darglint2）: コード内の引数名と、Docstringに記載した引数名が一致しているか、記述漏れがないかをチェックするには、darglint2 などのリンターを導入するのが効果的です。
• モダンなリンター（Ruff）: 最近のプロジェクトでは、Ruff を使用することで、Docstringの形式的な誤りや未記述を高速に検知することが推奨されています。

Python Docstringの書き方まとめ

今回のまとめ：振り返りチェックリスト

• Docstringは「使い手のガイド」： 単なる補足コメント（#）ではなく、help()関数やエディタのホバー表示で「関数の使い方」を正しく伝えるための仕組みであることを再認識しましょう。
• スタイルの統一が保守性の鍵： 可読性の高いGoogleスタイルや分析分野で強いNumPyスタイルなど、プロジェクトに最適なスタイルを一つ選び、チーム全体で一貫性を持たせることが大切です。
• ツールの活用で効率化： VS Codeの拡張機能（autoDocstringが最も人気ですが、他にもAI Python Docstring Generatorなど複数の選択肢があります）で入力を自動化し、Sphinxやpdocを使って「生きたドキュメント」を自動生成する環境を整えましょう。
• アドバイス： 最初から完璧を目指さなくても大丈夫です。まずは今日作成する関数のひとつに、Googleスタイルの「引数（Args）」と「戻り値（Returns）」を添えることから始めてみましょう！

Pythonの Docstring は、単なるソースコード内のメモに留まらず、開発チーム全体の生産性やコードの保守性を左右する重要なドキュメント資産と言えるでしょう。本記事で解説した内容を振り返り、実務で活用するためのポイントを整理します。

主要スタイルの特徴と選択の目安

プロジェクトの性質やチームの習熟度に応じて、以下の3つのスタイルから最適なものを選択することが一般的です。それぞれのスタイルには明確な強みがあるため、用途に合わせて使い分けるのが理想的かもしれません。

特にこだわりがない場合や、初心者の方が最初に取り組む場合は、書きやすさと読みやすさのバランスが良い Googleスタイル から導入してみるのがスムーズかもしれません。

高品質なDocstringを維持するための5つのポイント

適切な Docstring を記述し続けるためには、以下のチェックリストを意識することが有効です。これらを習慣化することで、誰にとっても読みやすいコードベースを構築できるでしょう。

1. 要約を1行目に書く: 最初の1行を読めば、その関数やクラスの役割が概ね理解できるように簡潔に記述します。
2. 型情報は型ヒントで補完する: 引数や戻り値の型は型ヒントで明示し、Docstringではその意味や制約を説明することで、IDEの補完機能を最大限に活用できます。
3. 例外（Raises）を隠さない: どのようなエラーが発生し得るかを明記することで、利用側の予期せぬクラッシュを防ぎ、エラーハンドリングを容易にします。
4. 「なぜ」を記述する: 実装の「方法」はコード自体が示しますが、API仕様に関わる前提条件や設計上の意図などは Docstring に残すと、利用者にとって理解しやすくなります。
5. 自動化ツールとの連携: Sphinx や pdoc を利用してHTMLドキュメントを自動生成し、コードと仕様書の乖離を防ぐ仕組みを作ります。

継続的なメンテナンスが価値を生む

Docstring は一度記述して満足するものではなく、コードの進化と共に更新し続ける必要があります。 最近では、Ruff という高速なリンターを導入するのが主流です。Ruffの Dルール（pydocstyle） を有効にすれば、Docstringの不足やフォーマット違反をリアルタイムで検知できます。これにより、個別のプラグイン（flake8-docstrings等）を管理する手間を省き、チーム全体で高品質なドキュメントを維持できます。

Pythonの標準的な書き方をマスターすることは、エンジニアとしての信頼性を高める第一歩です。読み手にとって親切なドキュメント作成を心がけることで、より堅牢でメンテナンス性の高いソフトウェア開発が可能になるはずです。

Pythonユーザにお勧めの本

人気

スッキリわかるPython入門 第2版 スッキリわかるシリーズ

📦 Amazonで見る 🔴 楽天で見る

独習Python

📦 Amazonで見る 🔴 楽天で見る

Python1年生 第2版 体験してわかる！会話でまなべる！プログラミングのしくみ

📦 Amazonで見る 🔴 楽天で見る