この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
DA事業本部の横山です。
みなさん、docstring書いていますか?
きちんと記載しておくとIDEのAutoComplete機能などから参照できるためとても便利なものですが、正直書くの面倒ですよね?
そこで、Pythonのdocstringを自動生成してくれるVSCode拡張機能Python Docstring Generatorを紹介したいと思います。
機能説明
ざっくりな機能はタイトルの通りのため、どのような動作をするのかをAWS LambdaをランタイムPython 3.8
で新規作成したコードを例に説明します。
新規作成されるLambdaのPythonコードは以下になります。
lambda_function.py
import json
def lambda_handler(event, context):
# TODO implement
return {
'statusCode': 200,
'body': json.dumps('Hello from Lambda!')
}
このコードのlambda_handler()
に対して、拡張機能でdocstrnigを自動生成させてみましょう。
関数宣言の直下で"""
を入力するとGenerate docstring
という入力支援が表示されるのでそのままEnterを押下することでdocstringが自動的に挿入されます。
lambda_function.py
import json
def lambda_handler(event, context):
"""[summary]
Args:
event ([type]): [description]
context ([type]): [description]
Returns:
[type]: [description]
"""
# TODO implement
return {
'statusCode': 200,
'body': json.dumps('Hello from Lambda!')
}
自動でGoogle styleのdocstringが挿入されました!
ちなみに[type]
については自動生成を行う前に、Pythonの型ヒントを記載しておくことで自動的に補完することも可能です!
自動生成されたdocstring内の[summary]
や[type]
, [description]
などを適宜修正するだけで、docstringが完成します。簡単ですね!
対応スタイル
現在は以下のスタイルに対応しているようです。
- Google (default)
- docBlockr
- Numpy
- Sphinx
個人的にはGoogle styleが簡潔にかけておすすめです。
最後に
Pythonのdocstringを自動生成してくれるVSCode拡張機能Python Docstring Generatorを紹介しました。
開発を行っているとついおろそかになりがちなdocstringですが、拡張機能を利用することで手軽にきれいに書くことができるようになりメンテナンス性を向上させることができます。
docstringを書く人が増え、この関数ってなにやってるんだっけ?となって困る人が少しでも減ることを祈っています。
以上になります。この記事がどなたかの助けになれば幸いです。