VSCodeでのPython開発でdocstringを自動生成してくれるPython Docstring Generatorについて紹介します。
Contents
Pythonにおけるdocstring
Pythonでプログラミング開発をしている際に、関数やクラスなどの仕様を利用者に対して分かるようにすることが必要です。ダブルクオート(“)を３つ連続して並べた三重引用符で囲んで記載した文字列をdocstringと言います。
例えば、docstringの例としては以下のような感じです。
def sample_func(temp1: int, temp2: int) -> int:
"""2変数の加算結果を返却する
Args:
temp1 (int): 数値1
temp2 (int): 数値2
Returns:
int: 加算結果
"""
return temp1 + temp2
このdocstringについては、自分でゼロから書いてももちろんいいのですが、関数の定義をベースに自動で生成して、細部を埋めていく方がはるかに楽です。
コードエディタであるVSCodeでは、拡張機能である「Python Docstring Generator」を使用することで、docstringを自動生成することが可能になります。
本記事では、Python Docstring Generatorをインストールや使い方、設定方法について紹介します。
Python Docstring Generatorの使い方
Python Docstring Generatorのインストール
Python Docstring Generatorは、Python拡張機能としてインストールできます。以下の手順でPython拡張機能をインストールしてください。
- 拡張タブを選択する。
- 検索窓で「docstring」と入力する。
- 検索された「autoDocstring – …」をクリックすると右側にPython拡張の説明が表示される。
- インストールをクリックしてPython拡張機能をインストールする。
上記のインストールを行うことでPython Docstring Generatorの機能が使用できるようになります。
Python Docstring Generatorの使い方
Python Docstring Generatorの使い方は簡単です。
開発しているPythonプログラムで関数を定義するときに、関数定義の下の行で以下のようにダブルクオート(“)を三つ入力すると「Generate Docstring」というように表示されるのでEnterを押します。
また、ダブルクオートを入力しなくても関数定義の下の行で「ctrl + shift + 2」とすることでも生成できますのでお好みの方法を利用してください。
実行すると以下のようにdocstringが自動生成されます。
_summary_や_description_のところを以下のように自分で書き換えればdocstringが完成します。
docstringを記載しておくと、以下のように呼び出しもとで関数にマウスのカーソルを合わせる等するだけ以下のように、関数の概要を把握することも可能になります。
Python Docstring Generatorの設定
Python Docstring Generatorでは、「google」スタイルのフォーマットがデフォルト設定となっています。
拡張機能のインストール一覧からPython Docstring Generatorの[歯車マーク]-[拡張機能の設定]をクリックすると設定を確認することができます。
以下のAuto Docstring: Docstring Formatの部分がフォーマットに関する設定になります。
プルダウンをクリックして見ると以下のように結構たくさんの種類がありますね。自分の好みやプロジェクトの方針により設定を変更して使用してください。
どのスタイルを使うのがよいのかという話があるかと思います。numpyスタイルか、googleスタイルかといったあたりがよく話が上がるような気がしますが、プロジェクトとして一貫していればいずれのフォーマットでも問題ないかと思います。
まとめ
VSCodeでのPython開発でdocstringを自動生成してくれるPython Docstring Generatorについて紹介しました。
Python Docstring Generatorのインストール、基本的な使い方、スタイルの設定について説明しています。docstringの記載は関数等の説明を利用者やプロジェクトメンバに伝える意味でも、プログラミングにおいて重要なことであると思っています。
ゼロから自分で書くのは少し面倒ですので、Python Docstring Generatorを活用して効率よく記載していってもらえるとよいかと思います。
