Python Docstrings

Python学習【365日チャレンジ!】53日目のマスターU(@Udemy11)です。

Youtubeをみてしまうと、ついつい次の動画を見てしまい、知らない間に時間が経ってしまっています。

Gyao!もだめですね。

とくに、単発の映画じゃなくて、続き物のあるアニメやドラマはほんと止められません。

きちっと時間を決めてタイマーをセットしておかないと、気づいたら夜中の丑三つ時なんてことになっちゃいます。

それでは、今日もPython学習をやっていきましょう!

昨日の復習

昨日は、キーワード引数の辞書化を学習しました。

位置引数のタプル化と同じように、キーワード引数は辞書型にして関数で使うことができて、 forループで値を出力することもできました。

def menu_func(**kwargs):
    for i, j in kwargs.items():
        print(i, j)
 
menu_func(drink='coffee', dessert='cake')

出力結果

drink coffee
dessert cake

関数menu_funcの実行時に代入されるキーワードと値が**によって辞書化されて、その後、items()メソッドでkeyとvalueを取り出して変数iとjに代入して出力しています。

位置引数、タプル化された位置引数とも一緒に使うことができましたが、注意が必要でした。

def menu_func(word, *args, **kwargs):
    print(word)
    print(args)
    print(kwargs)
 
menu_func('apple', 'banana', 'orange', food='beef', drink='tea')

出力結果

(apple)
('banana', 'orange')
{'food': 'beef', 'drink': 'tea'}

タプル化された位置引数と辞書化されたキーワード引数を一緒に使うときは、順番が重要で、*が2つの辞書化より、*一つのタプル化を前に持ってくる必要がありました。

また、タプル化ではほぼ使うことがないアンパッキングからの辞書化は、キーワード引数の辞書化ではよく使うとのことでした。

def dic_func(**kwargs):
    for i, j in kwargs.items():
        print(i, j)
 
d = {'fruit': 'apple', 'food': 'beef', 'drink': 'tea'}
dic_func(**d)

出力結果

fruit apple
food beef
drink tea

*を一つで使う場合も2つで使う場合も、実行時の関数で使うとタプル型や辞書型をアンパッキングする役割を持っていて、関数を定義する際に使う場合は、タプル型や辞書型にまとめる役割を持っていました。

辞書型のアンパッキングからの辞書化はしっかりと憶えておきましょう。

Docstrings

Docstringsは、関数のドキュメンテーションということですが、定義した関数がどんな構造になっているのかを解説した文書です。

他の言語であれば、関数の上部に解説が書いてあったりしますが、Pythonの場合は、def文の次の行に【”””】で囲んで記載します。

def example_func(param1, param2):
    """"Example function with types documented in the docstring.
 
    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.
 
    Returns:
        bool: The return value. True for success, False otherwise.
    """
    return True

これは酒井さんの講座で紹介されていたものですが、説明はすべて英語になっているんですよね。

講座の内容だけでは、Docstringsのことがわからなかったので、いろいろと調べてみると、書き方にもきちんとしたルールがあって、基本的には、英語で記載することを推奨しているみたいで、酒井さんの書き方はGoogleスタイルでの記載でした。

参考にしたのはこのあたりの記事

とはいえ、日本語を使う人しかいない環境でPython開発をしている場合は、日本語のほうが意味が伝わるし、英語だと間違った意味で捉えられる可能性がある場合は、日本語で書いたほうがいいみたいです。

初心者で、英語が苦手な人は、日本語で書いておいたほうがいいかもしれません。

もちろんPythonと一緒に英語を勉強するつもりがあったり、将来的にはグローバルなPythonエンジニアとして活躍したいのなら、英語でドキュメントを書く練習をしておいたほうがいいでしょう。

メソッドで呼び出せる

定義した関数は、最初から用意されている関数と同じように、メソッドでDocstringsを呼び出して確認することが可能です。

def example_func(param1, param2):
    """"Example function with types documented in the docstring.
 
    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.
 
    Returns:
        bool: The return value. True for success, False otherwise.
    """
    return True
 
print(example_func.__doc__)

出力結果

Example function with types documented in the docstring.
 
    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.
 
    Returns:
        bool: The return value. True for success, False otherwise.

最初から用意されている関数もDocstringsが用意されているので、【.__doc__】で表示させることもできます。

また、以前学習したhelp関数を使っても定義した関数の説明を表示することができます。

help(example_func)

出力結果

Help on function example_func in module __main__:
 
example_func(param1, param2)
    Example function with types documented in the docstring.
 
        Args:
            param1 (int): The first parameter.
            param2 (str): The second parameter.
 
        Returns:
            bool: The return value. True for success, False otherwise.

実際にプログラムを書く際に、関数を定義するときは、どのような動作をさせるのか書く必要が出てくるわけですが、今は、こんなルールがあって、関数に関しては説明が必要だということを理解しておくくらいでいいと思います。

説明がある理由

20年ほど前からWebサイトを作ったりしてたので、phpをかじったこともありました。

ただ、真剣に学習していたわけでなく、部分部分で使ってただけなので、スキルとして残ってはいませんが、当時から、処理する内容などが書かれているコードを見て、

それいる?

なんて思ってたんですよね。

でも、よくよく考えると、書いているコードがどんな意味を持っているのか書いておけば、バグの場所を見つけやすくなったり、他の人がコードを見たときに、どんな処理をしているのかわかりやすいわけですよね。

いちいち解説を書くのは面倒だと思いますが、このようなルールをきっちりと決めて、誰もがわかりやすい凡庸性の高いものにしているからこそ、Pythonが人気の言語になっているんだと思います。

まだDocstringsを使うレベルには達していませんが、Pythonの基礎基本をしっかりと学習していこうと思います。

それでは、明日もGood Python!