VSCode拡張機能「Python Docstring Generator」でPythonのdocstringを自動生成しよう

2020.10.29

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を書く人が増え、この関数ってなにやってるんだっけ?となって困る人が少しでも減ることを祈っています。

以上になります。この記事がどなたかの助けになれば幸いです。