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

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

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

 

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

 

 

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では、初心者でもPythonを使った人工知能（AI）や機械学習の基礎を習得できるオンラインブートキャンプPython講座を開催しています。

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