Pythonのdocstringを使う方法【初心者向け】

初心者向けにPythonでdocstringを使う方法について解説しています。docstringを使うことで関数やクラスに説明文を書くことができます。説明文の書き方とその決まりについて、例を見ながら学習していきましょう。

TechAcademyマガジンは受講者数No.1のオンラインプログラミングスクールTechAcademy [テックアカデミー]が運営。初心者向けに解説した記事を公開中。現役エンジニアの方はこちらをご覧ください。

Pythonのdocstringの使い方について解説します。

そもそもPythonについてよく分からないという方は、Pythonとは何なのか解説した記事を読むとさらに理解が深まります。

 

なお本記事は、TechAcademyのオンラインブートキャンプPython講座の内容をもとに紹介しています。

 

田島悠介

今回は、Pythonに関する内容だね!

大石ゆかり

どういう内容でしょうか?

田島悠介

docstringの使い方について詳しく説明していくね!

大石ゆかり

お願いします!

 

docstringとは

docstringとは、関数やクラスに対する説明文のことです。実際に表示して確認してみましょう。パソコンがMacの場合はターミナル、Windowsの場合はコマンドプロンプトから「python」と入力し、Pythonの対話型インタプリタを起動します。

なお、事前に Python のインストールが必要です。起動したら、以下のように入力します。

 print(range.__doc__)

実行結果は以下のようになります。range関数の説明文が表示されています。

range(stop) -> range object
range(start, stop[, step]) -> range object

Return an object that produces a sequence of integers from start (inclusive)
to stop (exclusive) by step. range(i, j) produces i, i+1, i+2, ..., j-1.
start defaults to 0, and stop is omitted! range(4) produces 0, 1, 2, 3.
These are exactly the valid indices for a list of 4 elements.
When step is given, it specifies the increment (or decrement).

このような説明文は、自分で作った関数やクラスにも書くことができます。

 

docstringの書き方

docstringの書き方は以下のとおりです。最初に関数に書く場合の例です。

def my_function1():
    """my_function1の説明文
    説明文2行目
    説明文3行目
    説明文4行目
    """

クラスに書く場合も同様です。

class MyClass1:
    """MyClass1の説明文
    説明文2行目
    説明文3行目
    説明文4行目
    """

説明文は関数名のすぐ下に書くようにします。間に変数などを定義すると docstring として認識されなくなります。また docstring は一般的に「”””」または「”’」で囲って記載ます。複数行記載することができます。

説明文は以下のどちらかの方法で表示することができます。開発環境によってはショートカットキーが用意されている場合もあります。

print(関数名.__doc__)
help(関数名)

なお、説明文は自由に書くことも出来ますが、いくつかフォーマットが存在しています。参考にしてみると良いでしょう。

Googleスタイル

その他、reStructuredTextスタイル、NumPyスタイルなどがあります。

 

[PR] Pythonで挫折しない学習方法を動画で公開中

実際に書いてみよう

今回のサンプルプログラムではmy_function1という関数に説明文を書いています。

def my_function1():
    """my_function1の説明文
    説明文2行目
    説明文3行目
    説明文4行目
    """

先の range 関数の例と同様、以下のように入力することで説明文を表示できます。

print(my_function1.__doc__)

実行結果は以下のようになります。

my_function1の説明文
    説明文1行目
    説明文2行目
    説明文3行目

次にhelpを使って表示してみましょう。

help(MyClass)

実行結果は以下のようになります。

Help on class MyClass in module __main__:

class MyClass(builtins.object)
 |  docstring-test
 |  line1
 |  line2
 |  line3
 |  
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

 

この記事を監修してくれた方

太田和樹(おおたかずき)
ITベンチャー企業のPM兼エンジニア

普段は主に、Web系アプリケーション開発のプロジェクトマネージャーとプログラミング講師を行っている。守備範囲はフロントエンド、モバイル、サーバサイド、データサイエンティストと幅広い。その幅広い知見を生かして、複数の領域を組み合わせた新しい提案をするのが得意。

開発実績:画像認識技術を活用した駐車場混雑状況把握(実証実験)、音声認識を活用したヘルプデスク支援システム、Pepperを遠隔操作するアプリの開発、大規模基幹系システムの開発・導入マネジメント

地方在住。仕事のほとんどをリモートオフィスで行う。通勤で消耗する代わりに趣味のDIYや家庭菜園、家族との時間を楽しんでいる。

 

大石ゆかり

内容分かりやすくて良かったです!

田島悠介

ゆかりちゃんも分からないことがあったら質問してね!

大石ゆかり

分かりました。ありがとうございます!

 

TechAcademyでは、初心者でも最短4週間でPythonを使った人工知能(AI)や機械学習の基礎を習得できるオンラインブートキャンプPython講座を開催しています。

挫折しない学習方法を知れる説明動画や、現役エンジニアとのビデオ通話とチャットサポート、学習用カリキュラムを体験できる無料体験も実施しているので、ぜひ参加してみてください。