【Python】docstringとは？初心者向けに使い方と活用方法を詳しく解説
はじめに
Pythonでプログラムを書くとき、コードの見やすさや分かりやすさを意識することが大切です。
そのために役立つのが、docstring と呼ばれる仕組みです。
docstringを使うと、モジュールやクラス、関数などの説明をコードの内部に直接書くことができます。
あいまいなコメントや単なるメモ書きとは違い、docstringはPythonが正式に解釈する文字列です。
たとえば、Pythonの対話モードで help() 関数を利用すると、docstringに書いた内容がそのままドキュメントとして表示される仕組みになっています。
この記事では、初心者の方にもわかりやすい言葉でdocstringの基本や書き方、実務での活用方法を解説していきます。
「なんとなくdocstringを入れているけれど、正式な書き方は知らない」という方も、ぜひ参考にしてみてください。
この記事を読むとわかること
- docstringの概要と基本的な書き方
- 関数やクラス、モジュールでの具体的な使い方
- スタイルによるdocstringの違い
- 実務での活用やチーム開発におけるメリット
- docstringを書くときのベストプラクティス
Python docstring とは
docstringとは、コード内で定義したモジュールやクラス、関数などの動作を説明するための文字列リテラルです。
Pythonでは慣例として三重引用符（""" または '''）を用いて記述し、コードに対して簡潔で理解しやすい説明を与えます。
多くのプログラミング言語ではコメントを使いますが、Pythonのdocstringはコメントと少し異なる特徴があります。
コメントはあくまでコードを読みやすくするための補助要素であり、Python自体がその情報を特別に利用するわけではありません。
一方、docstringは help() 関数やさまざまなドキュメンテーションツールによって、コードの正式な説明文として扱われます。
docstring とコメントの違い
- docstring: Pythonが公式に解釈する文字列。
help()などで参照できる - コメント:
#を使って書く単なるメモ。Pythonインタープリタは基本的に無視する
このdocstringを活用すると、コードの可読性や保守性を高めながら、必要に応じて自動ドキュメントを生成することも可能です。
docstring の基本的な書き方
docstringは、クラスや関数、モジュールの定義直後に三重引用符を使って書きます。
最もシンプルな例としては、以下のようになります。
def greet(name): """ 指定した名前のユーザーへ挨拶を行う関数。 引数: name (str): ユーザーの名前。 戻り値: なし。 """ print(f"こんにちは、{name}さん！")
このように三重引用符の間に説明を書き込むと、それが関数のdocstringになります。
Pythonの対話モードで help(greet) と入力すると、このdocstringに書いた内容が表示されます。
docstring を記述するときの注意点
docstringを書き始めるときは、最初の行で簡潔に関数やクラスの概要を伝えます。
続けて必要な引数、戻り値、注意点などの詳細情報を書いておくと、後から読み返したときに役立ちます。
初心者の方でも、後々のメンテナンスを考えて、なるべく分かりやすい日本語を心がけましょう。
1行docstringと複数行docstring
docstringには1行だけで書く方法と、複数行を使って書く方法があります。
1行docstringは、ごく簡単な関数やクラスに向いています。
複数行docstringは、引数や戻り値などの説明が複数行に渡る場合に使います。
1行docstringの例
def add(a, b): """二つの数値を足して結果を表示する。""" print(a + b)
複数行docstringの例
def subtract(a, b): """ 二つの数値を引き算して結果を返す。 引数: a (int or float): 減算される値 b (int or float): 引く値 戻り値: int or float: 演算結果を返す """ return a - b
docstring の実務での活用シーン
docstringはコードの説明を明示的に書くだけでなく、実務でも役に立つさまざまなシーンがあります。
IDE やエディタでの活用
多くのエディタやIDEには、docstringを利用した自動補完機能が備わっています。
関数を呼び出す際にdocstringで書いた説明や引数の情報がツールチップとして表示されることがあるため、コードを見なくても大まかな使い方を把握できます。
これにより、開発スピードが上がり、チーム内でのやりとりもスムーズになります。
チーム開発での活用
チーム開発では、複数人が同じコードベースを扱うため、誰かが書いた関数の意図や引数の意味をすぐに理解できると便利です。
docstringを丁寧に書いておけば、公式ドキュメントを読む感覚でコードを理解できるようになり、コードレビューの時間短縮にもつながります。
また、新人メンバーがプロジェクトに加わったときにも、docstringがあるコードは学習コストを下げる効果があります。
引数名や返り値の型などをあらかじめ書いておくことで、勘違いを防ぎやすくなるでしょう。
docstring の種類と書き方の違い
docstring自体は三重引用符の中にテキストを記述するだけですが、コミュニティではいくつか書き方の「スタイル」が存在します。
代表的なのは、Googleスタイル、NumPyスタイル、reStructuredTextスタイル の3種類です。
それぞれ文書化ツールと連携する場合や、チームの好みに合わせて使い分けられています。
Google スタイルの docstring
Googleが公開しているPythonスタイルガイドで紹介されている記述方式です。
引数や戻り値を見やすく整理して書きます。
def multiply(a, b): """ Multiply two numbers. Args: a (int): The first number. b (int): The second number. Returns: int: The result of a * b. """ return a * b
Args, Returns といった見出しを用いて、それぞれを分けて説明するのが特徴です。
Googleスタイルは簡潔かつ視覚的に分かりやすいと言われています。
NumPy スタイルの docstring
数値計算ライブラリのNumPyプロジェクトで採用されているスタイルです。
Googleスタイルに似ていますが、独自の書き方が追加されています。
def divide(numerator, denominator): """ Divide two numbers. Parameters ---------- numerator : int or float The number to be divided. denominator : int or float The number to divide by. Returns ------- float The result of the division. """ return numerator / denominator
Parameters や Returns の後にアンダースコアのラインを用いて見出しとして明確化しているのが特徴です。
科学技術計算やデータ分析の現場で好んで使われることが多いです。
reStructuredText スタイルの docstring
reStructuredTextはSphinxというドキュメンテーション生成ツールなどで使われるマークアップ言語の一種です。
独自の記法で引数や戻り値を指定します。
def power(base, exponent): """ Raises a base number to a power. :param base: The base number. :type base: int or float :param exponent: The exponent. :type exponent: int :return: The result of base raised to exponent. :rtype: float """ return base ** exponent
Sphinxなどのツールと組み合わせる場合に役立ちます。
引数や戻り値などを :param: や :return: で表記するため、一目で区別がつきます。
docstring を活用した効率的な開発
docstringは、ただ「説明をつける」だけでなく、さまざまな場面で開発を効率化するのに利用できます。
自動ドキュメンテーションツールとの連携
Sphinxやpydocなどのツールを使用すると、docstringから自動的にドキュメントを生成できます。
プロジェクト規模が大きくなると、すべてのモジュールやクラス、関数を手動でドキュメント化するのは手間がかかるかもしれません。
しかしdocstringが整備されていれば、それらをもとにHTMLやPDFといった形で資料を簡単に作成できます。
コードレビューでの有用性
チームでの開発では、レビュー段階でdocstringを参照しながらコードをチェックすることが多いです。
docstringがしっかりしていると、レビュー担当者はコードの意図を把握しながら指摘できるため、やり取りがスムーズになります。
お互いの意思疎通が円滑になり、手戻りも減らせるでしょう。
メンテナンス性の向上
docstringを書いておけば、久しぶりにコードを読み返すときや別の人が保守を担当するときに、理解を助けてくれます。
開発当時に意図していた仕様や関数の目的が書かれているので、時間が経ってからでも「この関数は何をするものか」を素早く思い出せます。
docstringを定期的にレビューし、実際の実装と説明が乖離していないか確認すると、長期的なメンテナンスコストを抑えやすくなります。
docstring のベストプラクティス
簡潔さと明確さ
docstringは丁寧に書くほど理解しやすくなりますが、長すぎると読む側が疲れてしまいます。
関数やクラスがやろうとしていることを簡潔かつ明確に伝え、重要な情報のみを盛り込みましょう。
引数・戻り値・例外の説明
引数が複数ある場合、それぞれが何を意味するのかを明示的に書くのが理想的です。
また、戻り値がある場合には、型や返す値の意味を一言添えておくと後から分かりやすくなります。
何らかの例外を発生させる可能性がある場合（ゼロ除算など）は、その点をdocstringに書いておくことで、使用者が事前に注意できます。
def safe_divide(a, b): """ 二つの数値を割り算して結果を返す。ただしbが0のときにはエラーを投げる。 引数: a (int or float): 割られる数 b (int or float): 割る数 戻り値: float: 割り算の結果 例外: ZeroDivisionError: bが0の場合に発生 """ if b == 0: raise ZeroDivisionError("0で割ることはできません。") return a / b
docstring の書き手と読み手を意識する
自分だけが読むのであれば、たとえば短いメモでも事足りるかもしれません。
しかし、チームのメンバーや将来の自分自身が再利用することを考慮し、読み手がスムーズに理解できるように書きましょう。
特に専門用語を必要以上に使わず、シンプルな言葉を選ぶことが大事です。
よくあるトラブルシューティング
docstring が正しく表示されない時
docstringが正しく表示されない主な原因は、関数やクラスの定義直後にdocstringを書いていないことが多いです。
また、インデントがずれている場合や、docstringの位置がほかのコードと混在している場合も問題につながります。
正しくは次のように、def や class の定義のすぐ下に三重引用符で囲んだdocstringを書く必要があります。
class ExampleClass: """ これはExampleClassのdocstringです。 このクラスがどのような役割を持つかを説明します。 """ def __init__(self, value): """ コンストラクタ。valueに初期値を設定します。 """ self.value = value
docstring の内容がわかりにくい時
docstringの中身がわかりにくい理由には、専門用語が多すぎるケースや、説明が抽象的すぎるケースがあります。
あるいは、関数の処理とdocstringに書いてある説明がずれてしまっていると、混乱を招いてしまいます。
こういった場合には、一度docstringと実際のコードを見比べて、処理内容と説明内容が一致するように修正しましょう。
専門用語を減らしたり、引数名や返り値の具体例を追加したりするだけでも、読みやすさは大きく変わります。
docstringに書かれた説明と実際の実装が変わっているまま放置すると、誤情報が広まる原因になります。 開発中に仕様変更があったら、docstringの更新も忘れないようにしましょう。
まとめ
docstringはPythonにおけるコードの説明手段であり、単にコメントを入れる以上のメリットがあります。
初心者の方でも、三重引用符の中に簡潔に要点を書くだけで十分に活用できます。
- 関数やクラスの定義直後に書く
- ArgsやParametersなどを使って引数の意味を分かりやすく解説
- 戻り値や例外がある場合には、その内容を忘れずに記述
- コードレビューや自動ドキュメンテーションツールとも相性が良い
Pythonのdocstringを活用すれば、コードの可読性と開発効率の両方が高まります。
これを機に自分のプロジェクトや学習中のコードにdocstringを取り入れてみてください。
今後のメンテナンス性を大きく向上させる手助けになるでしょう。