【Python初心者必見】docstringの書き方完全ガイド！読めるコードは「説明書」が違う
山崎講師こんにちは。ゆうせいです。
プログラミングの学習を始めたばかりのときって、とにかくコードを動かすことに夢中になりますよね。「コメントや説明文は後で書けばいいや…」なんて思っていませんか？実は、その「後で」が、未来のあなたやチームの仲間を救うことになるかもしれません。
今回は、Pythonコードの「説明書」とも言えるドキュメンテーション文字列（docstring）について、その役割から書き方まで、初心者の方にも分かりやすく解説していきます！
ドキュメンテーション文字列（docstring）って何？
まず、専門用語から見ていきましょう。
ドキュメンテーション文字列（docstring）とは、関数やクラス、モジュールといったPythonのオブジェクトが「何をするためのものか」「どうやって使うのか」を説明するために書く文字列のことです。
「え、それってコメントと同じじゃないの？」と思った方もいるかもしれませんね。良い質問です！
コメントとdocstringは似ていますが、目的が少し違います。
- コメント (
#): コードの断片が「なぜ」そのように書かれているのか、複雑な処理の「仕組み」はどうなっているのか、といった実装の詳細を説明するために使います。 - docstring (
"""..."""): その関数やクラスの「使い方」を説明します。いわば、家電製品についてくる取扱説明書のようなものです。中身の回路がどうなっているか（仕組み）は知らなくても、説明書を読めばボタンの押し方（使い方）が分かりますよね。
docstringは、コードの使い手（他のエンジニアや未来の自分）のために書く、公式な「取扱説明書」だと考えてみてください。
docstringの基本的な書き方とメリット
docstringの書き方はとてもシンプルです。説明したい関数などの定義のすぐ下に、文字列をトリプルクォート（"""）または（'''）で囲んで記述するだけです。
基本的な書き方
例えば、2つの数値を足し算する簡単な関数を考えてみましょう。
def add(a, b):
"""2つの数値を受け取り、その和を返します。"""
return a + b
たったこれだけです！簡単ですよね？この一行があるだけで、このadd関数が何をするものなのかが一目瞭然になります。
docstringを書くメリットは？
「でも、たったこれだけのために書くのって面倒じゃない？」と感じるかもしれません。しかし、docstringには手間をかけるだけの価値がある、素晴らしいメリットがいくつもあるんです！
1. コードの可読性が劇的に向上する
数ヶ月後に自分のコードを見返したとき、「これ、何のために書いたんだっけ…？」と頭を抱えた経験はありませんか？docstringがあれば、コードのロジックを一行一行追わなくても、その関数が何をするものなのかをすぐに思い出せます。
2. チーム開発がスムーズになる
チームで開発を行う場合、他の人が書いた関数を使う場面がたくさんあります。そんなとき、docstringがあれば、関数の使い方をすぐに理解でき、開発効率が格段に上がります。いちいち「この関数の使い方、教えてください」と聞く手間が省けるわけです。
3. ヘルプ機能で使い方を確認できる
Pythonにはhelp()という便利な組み込み関数があります。このhelp()関数に自作の関数を渡すと、なんとdocstringに書いた内容が表示されるのです！
help(add)
これを実行すると、ターミナルに以下のような出力が表示されます。
Help on function add in module __main__:
add(a, b)
2つの数値を受け取り、その和を返します。
これで、いつでも関数の使い方を確認できますね。
4. ドキュメントを自動生成できる
Sphinxなどのツールを使うと、コード内のdocstringを自動的に収集して、Webサイトのような美しい形式の公式ドキュメントを生成できます。多くの有名なPythonライブラリのドキュメントは、この方法で作られているんですよ。
もっと詳しく書く！docstringのスタイル
一行だけの簡単な説明でも十分役立ちますが、より複雑な関数になってくると、引数や戻り値についての詳しい情報も書きたくなりますよね。
実は、docstringにはいくつかの推奨される書き方のスタイル（規約）が存在します。ここでは、Googleが推奨している読みやすいスタイル「Googleスタイル」を紹介します。
def divide(a, b):
"""2つの数値を除算します。
Args:
a (int or float): 割られる数（分子）。
b (int or float): 割る数（分母）。
Returns:
float: aをbで割った結果を返します。
Raises:
ZeroDivisionError: bが0の場合に、この例外を送出します。
"""
if b == 0:
raise ZeroDivisionError("0で割ることはできません。")
return a / b
このように、Args（引数）、Returns（戻り値）、Raises（送出する例外）といったセクションに分けて書くことで、関数の仕様が非常によく分かります。
デメリットも知っておこう
もちろん、良いことばかりではありません。docstringには注意すべき点もあります。それはメンテナンスのコストがかかることです。
もし、関数の仕様を変更したのにdocstringを更新し忘れると、docstringの情報が古くなり、コードと食い違ってしまいます。これは、間違った説明書を読むようなもので、かえって混乱を招く原因になります。
コードを修正したら、必ずdocstringも一緒に修正する！この習慣を忘れないでください。
まとめ：これからの学習に向けて
今回は、Pythonのdocstringについて解説しました。docstringは、単なるコメントではなく、コードの価値を高め、あなたやチームを助けてくれる強力なツールです。
- docstringはコードの「取扱説明書」
- 関数などの定義の直下に
"""..."""で記述する - コードの可読性を高め、チーム開発を円滑にする
help()関数やドキュメント自動生成ツールで活用できる- コードを修正したら、docstringも必ず更新する
今日から、あなたが書くすべての関数に、まずは一行でも良いのでdocstringを書いてみる習慣をつけてみませんか？
その小さな一歩が、あなたを「ただ動くコードを書く人」から「誰にでも分かりやすい、質の高いコードを書けるエンジニア」へと成長させてくれるはずです。
次に学ぶステップとしては、Sphinxのようなドキュメント自動生成ツールを実際に使ってみることをお勧めします。自分の書いたdocstringが綺麗なWebページに変換される様子を見ると、きっと感動しますよ！
セイ・コンサルティング・グループの新人エンジニア研修のメニューへのリンク
投稿者プロフィール
- 代表取締役
-
セイ・コンサルティング・グループ株式会社代表取締役。
岐阜県出身。
2000年創業、2004年会社設立。
IT企業向け人材育成研修歴業界歴20年以上。
すべての無駄を省いた費用対効果の高い「筋肉質」な研修を提供します！
この記事に間違い等ありましたらぜひお知らせください。
