【Python】よくわかるdocstring（ドキュメント文字列）の書き方【入門第39回】
目次
- docstringとは？
- 関数のdocstringの書き方
- クラスのdocstringの書き方
- docstringの参照
- helpクラスによるdocstringの参照
- docstringのスタイル
- おわりに
- 関連動画
docstringとは？
こんにちは、narupoです。
今回はPythonのdocstring（ドキュメント文字列）の使い方を解説します。
このdocstringを使うと、関数やクラスをドキュメント化することができるようになります。
関数やクラスをドキュメント化しておけば、未来の自分や他の開発者の人の助けになるでしょう。
具体的には↓を見ていきます。
関数のdocstringの書き方
クラスのdocstringの書き方
docstringの参照
helpクラスによるdocstringの参照
docstringのスタイル
関数のdocstringの書き方
関数のdocstringは↓のように書きます。
:::python
def func():
"""
ドキュメント内容
ドキュメント内容
ドキュメント内容
"""
pass
関数の内側にダブルクォーテーション（"）を3つ並べてdocstringを開始します。
その次にドキュメントの内容を書きます。
そして再びダブルクオーテーションを3つ並べてdocstringを閉じます。
これで完了です。
ダブルクオーテーションでなくシングルクォーテーション（'）3つで囲っても同様にdocstringになります。
:::python
def func():
'''
ドキュメント内容
ドキュメント内容
ドキュメント内容
'''
pass
docstringは関数のコロン（:）の直後の最初の行に書かなくてはいけません。
ですので↓のようにコロンの直後の最初の行に式などを書くと、docstringとして認識されません。
:::python
def func():
1 + 2
"""
ドキュメント内容
ドキュメント内容
ドキュメント内容
"""
pass
また、関数のコロンの直後の最初の行に文字列があれば、それがdocstringになるので、↓のように3連引用符でなくてもdocstringとして認識されます。
:::python
def func():
"ドキュメント内容"
pass
クラスのdocstringの書き方
クラスにdocstringを書くには↓のようにします。
:::python
class MyClass:
"""
ドキュメント内容
ドキュメント内容
ドキュメント内容
"""
pass
クラスのコロン（:）の直後の最初の行に文字列を書くと、それがdocstringになります。
あとは関数のdocstringと同じです。
メソッドのdocstringの書き方
クラスのメソッドにdocstringを書くには↓のようにします。
:::python
class MyClass:
def my_method():
"""
ドキュメント内容
ドキュメント内容
ドキュメント内容
"""
pass
これも関数のdocstringと同じです。
docstringの参照
関数やクラスのdocstringを参照するには__doc__属性を使います。
たとえば↓のような関数があるとします。
:::python
def cook():
"""
この関数は、
美味しい料理を作ります。
"""
pass
このcook関数のdocstringを参照するには↓のようします。
:::python
print(cook.__doc__)
↑のコードの実行結果は↓のようになります。
この関数は、
美味しい料理を作ります。
クラスやクラスのメソッドのdocstringも同様です。
↓のようなクラスがあるとすると、
:::python
class Cat:
"""
このクラスは世界一可愛いです。
でも、ちょっとおっちょこちょいです。
"""
def scratch(self):
"""
相手をひっかいて、
瀕死の重傷を負わせます。
"""
pass
↓のように参照することができます。
:::python
print(Cat.__doc__)
print(Cat.scratch.__doc__)
helpクラスによるdocstringの参照
docstringの威力がいかんなく発揮されるのは、helpクラスで参照されたときです。
たとえば先ほどのcook関数を
:::python
def cook():
"""
この関数は、
美味しい料理を作ります。
"""
pass
helpクラスで参照してみましょう。
:::python
help(cook)
↑のコードの実行結果は↓のようになります。
:::text
Help on function cook in module __main__:
cook()
この関数は、
美味しい料理を作ります。
このようにhelpクラスは、docstringからドキュメントを生成します。
たとえば↓のようなクラスがあるとして、
:::python
class Cat:
"""
このクラスは世界一可愛いです。
でも、ちょっとおっちょこちょいです。
"""
NAME = 'ミケ'
def scratch(self):
"""
相手をひっかいて、
瀕死の重傷を負わせます。
"""
pass
def shout(self):
"""
かなぎり声をあげて、
周りの人間を気絶させます。
"""
psas
このクラスを↓のようにhelpクラスで参照すると、
:::python
help(Cat)
↓のようなドキュメントになります。
:::text
Help on class Cat in module __main__:
class Cat(builtins.object)
| このクラスは世界一可愛いです。
| でも、ちょっとおっちょこちょいです。
|
| Methods defined here:
|
| scratch(self)
| 相手をひっかいて、
| 瀕死の重傷を負わせます。
|
| shout(self)
| かなぎり声をあげて、
| 周りの人間を気絶させます。
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| NAME = 'ミケ'
このようにhelpクラスを使うと、関数やクラスのdocstringを参照できるようになります。
これは、もちろん標準ライブラリや組み込み関数・クラスでも同様です。
試しにprint関数のdocstringを参照してみましょう。
:::python
help(print)
↑のコードの実行結果は↓のようになります。
:::text
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
helpクラスを使えばプログラミングで使うモジュールや関数、クラスなどの使い方を把握することができます。
これは便利なので覚えておきましょう。
英語だけどね
だいじょうぶ、Google翻訳がある
docstringのスタイル
docstringで3連引用符を使った場合、最初の3連引用符の直後に改行を入れるスタイルと、入れないスタイルがあります。
たとえば↓のようにです。
:::python
def f1():
"""
これは3連引用符の直後に改行を
入れるスタイルです。
"""
pass
def f2():
"""これは3連引用符の直後に改行を
入れないスタイルです。
"""
pass
どちらのスタイルを使うべきなのかは具体的には定められていません。
プロジェクトでこのスタイルを決めておくと、docstringの統一感が得られるかもしれません。
おわりに
docstringは未来の自分への贈り物です。
「なにもすることがないな～、暇だな～」となったら、docstringを書きましょう！
以上、次回に続きます。
また見てね