📝 「このコード、何だっけ？」を未来の自分に言わせない技術
1年前、自分が書いたコードを見返した瞬間に固まったこと、ありませんか？「この関数、何のために作ったんだっけ……」「引数に何を渡せばいいんだろう？」――そんな未来の混乱をスッと解決してくれるのが、Pythonのdocstring（ドキュメンテーション文字列）です。
たった数行のメモを残しておくだけで、エディター上にポップアップで関数の説明が現れたり、チームメンバーが迷わず使えたり、半年後の自分が「過去の自分、ありがとう🙏」と感謝したくなる未来が手に入ります。今日からあなたのコードに、ちょっとした「親切」を仕込んでみましょう✨
📚 docstringとは何か
docstringとは、コードの中に書くドキュメント文字列のこと。関数・クラス・モジュールの先頭に、それらに関する説明を記載するためのものです。たとえば「この関数は消費税込みの金額を計算する関数です」「このクラスは管理者ユーザーを表します」「このモジュールはロガー設定をまとめたものです」――こうした説明を、コードと一体化させて残せます。
docstringは絶対に書かないといけないものではなく、プログラムの処理を変化させる役割もありません。でも、書かずに済ませた未来と、書いておいた未来とでは、開発の快適さがまったく違うんです😌
自分で書いたコードなんて忘れるわけないよと思うかもしれませんが、1年前2年前に書いたコードは、思っている以上に忘れてしまうものです。
🎯 docstringを書くべき3つの場面
docstringが特に効果を発揮するのは、次のような場面です。
- 🤝 他の人と共有するコード：チームメンバーや、自作モジュールを公開して使ってもらうとき
- 🔍 後から見返すことがあるコード：数か月後、数年後の自分のために
- 💡 処理が一目で分かりにくいコード：逆に、処理が単純で明確な関数（例：単純なゲッターやイニシャライザ）はdocstringを省略してもOK
書くタイミングとしては、コーディング途中よりも「この部分はほぼ完成したな」というタイミングがおすすめ。書きながら書くのは少し面倒なので、機能が一段落してから一気に整えると効率的です⚡
🎨 主要な2つのスタイル：reStructuredText vs Googleスタイル
docstringにはいくつかの記法スタイルがあります。Pythonの公式ドキュメントで紹介されているのはreStructuredTextスタイル。一方、横に広く読みやすいGoogleスタイルも人気で、こちらを好むエンジニアも多いです。基本的に書く内容は同じで、フォーマットだけが少し違います。
📐 reStructuredTextスタイルの例
引数や戻り値を「:param 引数名: 説明」「:type 引数名: 型」「:return: 戻り値の説明」「:rtype: 戻り値の型」といった形で縦に並べていくスタイルです。情報が整理されますが、どうしても縦に長くなりがち。
📊 Googleスタイルの例
「Args:」「Returns:」「Raises:」といったセクション見出しの下にインデントして、引数や戻り値をまとめて書くスタイル。視認性が高く、関数のシグネチャをパッと把握しやすいのが魅力です。たとえば消費税込みの合計金額を計算する関数なら、Argsの下に「amount」「postage」「tax_rate」をまとめて並べられて、とてもスッキリ書けます🎉
🛠️ エディターの自動生成機能を活用しよう
「毎回手で書くのは面倒……」そんなときは、エディターの自動生成機能の出番です。
🐍 PyCharmの場合
関数の直後に """ を入力してEnterを押すと、現在の引数を解析して説明欄と型欄を自動生成してくれます。デフォルトはreStructuredTextスタイルですが、設定画面の「Tools → Python Integrated Tools → Docstring format」からGoogleスタイルに変更可能。一度設定しておけば、その後はずっとGoogleスタイルで自動生成されるようになります✨
💻 VS Codeの場合
拡張機能「Python Docstring Generator」を入れておけば、関数の下で """ を入力したときに表示される「Generate Docstring」を押すだけで、引数の型まで自動判別してdocstringを生成してくれます。デフォルトがGoogleスタイルなので、Googleスタイル派には特におすすめ。reStructuredTextに変えたいときは、拡張機能の設定で「Sphinx」に変更すればOKです🔧
🏗️ モジュール・クラス・関数それぞれの書き方
📦 モジュールのdocstring
Pythonファイルの一番上、import文よりも前に、3つのダブルクォートで囲んで記載します。1行で簡潔にモジュールの役割を書いてもいいですし、改行して複数行にわたって詳細を書いてもOK。著者情報やライセンスなどもここに書くのが定番です。
🏛️ クラスのdocstring
クラス定義（class クラス名:）のすぐ下に、3つのダブルクォートで括って書きます。クラスの説明に加え、外部に公開しているインスタンス変数の説明も記載できます。reStructuredTextなら「:ivar 変数名: 説明」「:vartype 変数名: 型」、Googleスタイルなら「Attributes:」セクションでまとめて書きます。
⚙️ 関数・メソッドのdocstring
関数定義（def 関数名(引数):）のすぐ下に、要約を1行で書き、空行を挟んでから詳細説明、引数（Args）、戻り値（Returns）、例外（Raises）を順に記載します。クラスのメソッドも、関数とまったく同じ書き方でOK👌
📖 docstringとPythonコーディング力を底上げする書籍5選
docstringの書き方は、結局のところ「読みやすいコードとは何か」「チームで開発するとはどういうことか」という大きなテーマと地続きです。ここでは、docstringの背景にあるPythonの作法やチーム開発の知見まで深く学べる書籍を厳選して紹介します📚
1. 読みやすいコードの哲学を身につける
変数名・コメント・関数の長さ・docstringのあり方まで、「コードを読む人」を意識した書き方の原則が詰まった世界的名著。docstringを書く意味を腹落ちさせたい人に、最初の一冊として強くおすすめです🌟
2. PythonらしさとPEP準拠の書き方を学ぶ
Pythonの設計思想、型ヒント、デコレーター、そしてdocstringを含むドキュメンテーション規約まで網羅的に解説。「動く」から「美しく動く」へとレベルアップしたい中級者にぴったりの一冊です🐍
3. 保守性と堅牢性を極めたい人へ
型ヒント・docstring・テスト・例外設計など、長期にわたって生き残るコードを書くための実践的なノウハウが詰まった一冊。「半年後の自分が困らないコード」を目指すならぜひ手に取ってほしい本です🛡️
4. チーム開発とドキュメントの作法を学ぶ
SphinxやMkDocsなどを使ってdocstringから自動的に美しいドキュメントを生成する手法も含め、チーム開発に必要な知識を実践的に解説。「書いたdocstringを資産化したい」と考える人に最適です📘
5. これからPythonを始める人の安心の入門書
関数・クラス・モジュールという基礎概念から丁寧に学べる定番の入門書。docstringを書く前提となる「関数とは何か」「クラスとは何か」をしっかり押さえたい初心者にぴったりです🌱
❓ よくある質問（FAQ）
🤔 docstringはコメント（#）と何が違いますか？
コメント（#）はコードの「読み手」だけが見るもので、実行時には完全に無視されます。一方docstringは __doc__ 属性として実行時にもアクセスでき、help() 関数やエディターのポップアップ、自動ドキュメント生成ツール（Sphinxなど）にも利用される「公式の説明」として扱われます。
📐 reStructuredTextとGoogleスタイル、どちらを選ぶべき？
個人開発なら好みでOKですが、チーム開発では必ずチームのルールに従うのが鉄則です。新規プロジェクトで自分で選べる場合は、横に広くて読みやすいGoogleスタイルが人気。Sphinxとの親和性を重視するならreStructuredTextが無難です。
🛠️ すべての関数にdocstringを書く必要はありますか？
必須ではありません。処理が単純で名前から役割が一目瞭然な関数（小さなゲッター、単純な __init__ など）は省略してもOKとされることが多いです。逆に、外部公開する関数や、引数・戻り値が複雑な関数には必ず書いておきましょう。
📝 docstringから自動でドキュメントを生成できますか？
はい、できます。代表的なのがSphinxで、reStructuredTextスタイルのdocstringから美しいHTMLドキュメントを自動生成してくれます。Googleスタイルを使う場合は「Napoleon拡張」を入れればSphinxでも扱えます。MkDocsとmkdocstringsの組み合わせも近年人気です。
⏰ docstringはいつ書くのがベスト？
書きながら書くと思考が中断されがちなので、機能が一段落して「ほぼ完成した」と感じたタイミングがおすすめ。エディターの自動生成機能を使えば、引数欄が用意された状態からスタートできるので、書く心理的ハードルもぐっと下がります。
🎁 まとめ：未来の自分とチームへのプレゼントとしてのdocstring
docstringは、書くのに少し手間がかかるけれど、その何倍ものリターンを未来にもたらしてくれる小さな投資です。エディターの自動生成機能を活用すれば手間は最小限、効果は最大限。今日からあなたのコードに「未来への思いやり」を一行ずつ仕込んでいきましょう✨
そして、書き方の原則やPythonの哲学を体系的に学ぶには、やはり書籍が最強の味方です。今回紹介した5冊から気になるものを手に取って、「読まれるコード」を書けるエンジニアへと一歩踏み出してみてください📘🚀
コメント