本日はPython入門記事です。
本日のテーマはこちら！
Pythonのコメントの書き方
Pythonのインラインコメントは#始まりで記述します。#以降の記述がコメントとして扱われます。
# 挨拶する def hello(name): print('Hello {} !'.format(name))
では、複数行のコメント、ブロックコメントはどう記述するのでしょうか？
# 挨拶する # 引数: name # 挨拶する名前 def hello(name): print('Hello {} !'.format(name))
Javaだと/*と*/で囲えばブロックコメントになったりと、言語によってはインラインコメントとブロックコメントで異なる記述方法をしますが、
では、ダブルクォーテーションまたはシングルクォーテーション3つに囲まれた以下の記述方法は見たことあるでしょうか？
def hello(name): """挨拶する Args: name (str): 挨拶する名前 """ print('Hello {} !'.format(name))
ダブルクォーテーションまたはシングルクォーテーション3つに囲まれた箇所は、プログラムでは動作しないので、コメントのように定義できますが、Pythonの定義上はStr型になります。
ダブルクォーテーション3つはコメント？
docstringでも複数行をコメントアウトするような使い方ができなくもないですが、注意が必要です。
例えば以下のようなリストの2つをコメントアウトする時に、ダブルクォーテーション3つで囲ってしまうと、囲った箇所が文字列を判定され、かつ末尾のカンマがなくなるためにエラーになります。
sample_list = [
100,
200,
"""
400,
800,
"""
1600,
]
for v in sample_list:
print(v)
実行結果
$ python main.py File "main.py", line 8 1600, ^ SyntaxError: invalid syntax
docstringとは
docstringはモジュール、クラス、メソッドの直下に記述します。
docstringにはGoogleスタイル、numpyスタイルなどの記述方法があります。
今回はGoogleスタイルを例に記述しています。
各スタイルの記述方法については以下の記事が参考になると思います！
docstringを書くメリットとして、
- ソースコードを読んだ時にクラスやメソッドの説明があるとわかりやすい
- VSCodeなどの統合開発環境のスニペットに説明を表示できる
- ドキュメント生成ツールに利用ができる
などが挙げられます。
docstringの書き方
以下のような、bird.pyというモジュール、クラス、メソッド全てにdocstringを記述したファイルを用意しました。
"""バードモジュール バードクラスを定義する。 """ class Bird: """バードクラス Note: バードクラス、飛べる鳥は飛べる Attributes name (str): 名前 color (str): 色 flyable (bool): 飛ぶことができるかどうか """ def __init__(self, name, color, flyable=True): """初期化 Args: name (str): 名前 color (str): 色 flyable (bool, optional): 飛ぶことができるかどうか Defaults to True. """ self.name = name self.color = color self.flyable = flyable def fly(self): """飛ぶ Raises: Exception: flyableがFalseの場合、飛ぶことができない Returns: str: 飛んだことを示すメッセージ """ if not self.flyable: raise Exception('{} cannot fly...'.format(self.name)) return '{} fly!'.format(self.name)
まずモジュール(=ファイル名)の説明は、ファイルの先頭に記述します。このモジュール内で何が定義されているかを記述します。
"""バードモジュール バードクラスを定義する。 """
クラスの説明は、クラス名の下に記述します。docstringそのものはクラス内の要素であるため、インデントが必要です。
class Bird: """バードクラス Note: バードクラス、飛べる鳥は飛べる Attributes name (str): 名前 color (str): 色 flyable (bool): 飛ぶことができるかどうか """
メソッドの説明も、メソッド名の下にインデントして記述します。メソッドの引数、戻り値、発生する例外などを記述できます。
def __init__(self, name, color, flyable=True):
"""初期化
Args:
name (str): 名前
color (str): 色
flyable (bool, optional): 飛ぶことができるかどうか Defaults to True.
"""
def fly(self):
"""飛ぶ
Raises:
Exception: flyableがFalseの場合、飛ぶことができない
Returns:
str: 飛んだことを示すメッセージ
"""
Note、Attributes、Args、Returns、Raisesなどの記述方法は以下を参考に記述しましょう。
sphinxcontrib-napoleon.readthedocs.io
docstringをVSCodeで書くなら拡張機能「Python Docstring Generator」がおすすめ！
VSCodeでPythonをコーディングしているのであれば、拡張機能の「Python Docstring Generator」を利用するのがおすすめです！インストールすれば、メソッドやクラス名の下でCtrl + SHift + 2でdocstringの雛形を自動生成可能です。Googleスタイルなどのスタイルも指定できます。
docstringとコードスニペット
これを別のPythonファイルでimportして、docstringがどのように役立つのかを見ていきましょう。
以下のPython拡張機能がインストールされている環境で検証しています。
まずはbird.pyをimportしたとき、モジュ－ルの説明が見れます。
birdモジュール内のBirdクラスを入力しようとしたとき、以下のようにスニペットにクラスに記述したdocstringが表示されます。
Bird()と入力すると、__init__()のdocstringが表示されます。Argsを記述していると、入力中のパラメータの説明が上部に表示されます。
インスタンスメソッドも同様にスニペットでdocstringが表示されます。
以上で確認できたとおり、docstringを記述しておけば、そのモジュールを呼び出す時に、毎回定義を確認しなくてすみます。
まとめ
以上、今回はPythonのコメントとdocstringについてをまとめました。
誰が見てもわかるコメント、docstringを書くことはプログラミング上達のために欠かせない能力です。特にdocstringを簡潔に書くことができれば、メソッドやクラス分けも適切に行うことができ、読みやすいコードになると思います。
