読み出せる説明を書く

01 / 07

コメントはPythonから見えない

第1章で # のコメントを覚えたね。あれはPythonが完全に無視するものだった。

つまり、コメントに何を書いてもプログラムからは読み出せない。下のコードで aisatsu.__doc__ を見てみると、None しか返ってこないよ。

def aisatsu():    # あいさつを表示する    print("おはよう")aisatsu()print(aisatsu.__doc__)

実行結果

おはよう
None

02 / 07

docstring の形

def の次の行に、""" で囲んだ文字を置いてみよう。これを docstring(ドックストリング)と呼ぶよ。「ドキュメント用の文字列」という意味だね。

さっきと同じように __doc__ を見ると、今度は書いた文字がそのまま返ってくる。Pythonが「この関数の説明」として覚えていてくれるんだ。

def aisatsu():    """あいさつを表示する"""    print("おはよう")aisatsu()print(aisatsu.__doc__)

実行結果

おはよう
あいさつを表示する

03 / 07

help() でも読める

もうひとつ、help() という組み込み関数からも読める。こちらは関数の形と説明をまとめて見せてくれるよ。

help(aisatsu)

こう書くと、関数の名前とかっこの中身、そして docstring が並んで表示される。Pythonを対話的にさわりながら「これ何だっけ」を調べるときの定番だよ。

表示の形はPythonのバージョンで少し変わるので、ここでは「そういう道具がある」とだけ覚えておこう。

04 / 07

1行 docstring

まずは1行の形から。何をする関数なのかを1文で書くよ。

コツは動詞で書くこと。「たし算」ではなく「2つの数を足した結果を返す」。名詞で止めると、何が起きるのかが伝わらないんだ。

短い関数なら、これだけで十分だよ。

def tashizan(a, b):    """2つの数を足した結果を返す。"""    return a + bprint(tashizan(2, 3))print(tashizan.__doc__)

実行結果

5
2つの数を足した結果を返す。

05 / 07

複数行 docstring

説明が長くなるときは複数行にする。形はだいたい決まっていて、こんな並びだよ。

1行目に要約を1文
空行を1つ
引数の説明
返り値の説明
閉じる """ は独立した行に置く

__doc__ で取り出すと、書いた改行もふくめて1つの文字列になっている。行の頭の字下げはPythonが取りのぞいてくれるので、左にそろって出てくるよ。

def waru(a, b):    """aをbで割った商を返す。    a: 割られる数    b: 割る数    """    return a // bprint(waru(7, 2))print(waru.__doc__)

実行結果

3
aをbで割った商を返す。

a: 割られる数
b: 割る数

06 / 07

クラスとメソッドにも書ける

書けるのは関数だけではないよ。クラスの class 行の下にも、メソッドの def 行の下にも同じように置ける。

取り出すときは クラス名.__doc__ と クラス名.メソッド名.__doc__。それぞれ別々に覚えられているんだ。

class Kudamono:    """くだものを1つ表す。"""    def __init__(self, namae, nedan):        self.namae = namae        self.nedan = nedan    def hyouji(self):        """名前と値段を表示する。"""        print(f"{self.namae}は{self.nedan}円")ringo = Kudamono("りんご", 150)ringo.hyouji()print(Kudamono.__doc__)print(Kudamono.hyouji.__doc__)

実行結果

りんごは150円
くだものを1つ表す。
名前と値段を表示する。

07 / 07

何を書いて、何を書かないか

書くのは外から使う人が知りたいことだよ。

何をするのか
どんな引数を渡すのか
何が返ってくるのか

逆に、中でどう計算しているかは書かない。それはコードを読めば分かるし、中身を直すたびに説明も直さないといけなくなる。

コメント(#)との使い分けはこう。docstring は「外から見た使いかた」、コメントは「中で、なぜそうしたか」。置く場所も読む相手も違うんだよ。