【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
を書きましょう!
以上、次回に続きます。
また見てね