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

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

TechAcademyマガジンはオンラインのプログラミングスクールTechAcademy [テックアカデミー]が運営する教育×テクノロジーのWebメディアです。初心者でもすぐ勉強できる記事が2,000以上あります。

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ではPythonを使って機械学習の基礎を学ぶPythonオンライン講座を開催しています。

初心者向けの書籍を使って人工知能(AI)や機械学習について学ぶことができます。

現役エンジニアがパーソナルメンターとして受講生に1人ずつつき、マンツーマンのメンタリングで学習をサポートし、最短4週間で習得することが可能です。

また、現役エンジニアから学べる無料のプログラミング体験会も実施しているので、ぜひ参加してみてください。