VSCode

VSCodeの「Python Docstring Generator」拡張機能でdocstringを自動生成する

VSCodeの「Python Docstring Generator」拡張機能でdocstringを自動生成する

VSCodeでのPython開発でdocstringを自動生成してくれるPython Docstring Generatorについて紹介します。

Pythonにおけるdocstring

Pythonでプログラミング開発をしている際に、関数やクラスなどの仕様を利用者に対して分かるようにすることが必要です。ダブルクオート(")を3つ連続して並べた三重引用符で囲んで記載した文字列を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拡張機能をインストールしてください。

  1. 拡張タブを選択する。
  2. 検索窓で「docstring」と入力する。
  3. 検索された「autoDocstring - ...」をクリックすると右側にPython拡張の説明が表示される。
  4. インストールをクリックしてPython拡張機能をインストールする。
Python Docstring Generator

上記のインストールを行うことでPython Docstring Generatorの機能が使用できるようになります。

Python Docstring Generatorの使い方

Python Docstring Generatorの使い方は簡単です。

開発しているPythonプログラムで関数を定義するときに、関数定義の下の行で以下のようにダブルクオート(")を三つ入力すると「Generate Docstring」というように表示されるのでEnterを押します。

Python Docstring Generator

また、ダブルクオートを入力しなくても関数定義の下の行で「ctrl + shift + 2」とすることでも生成できますのでお好みの方法を利用してください。

実行すると以下のようにdocstringが自動生成されます。

Python Docstring Generator

_summary_や_description_のところを以下のように自分で書き換えればdocstringが完成します。

Python Docstring Generator

docstringを記載しておくと、以下のように呼び出しもとで関数にマウスのカーソルを合わせる等するだけ以下のように、関数の概要を把握することも可能になります。

Python Docstring Generator

Python Docstring Generatorの設定

Python Docstring Generatorでは、「google」スタイルのフォーマットがデフォルト設定となっています。

拡張機能のインストール一覧からPython Docstring Generatorの[歯車マーク]-[拡張機能の設定]をクリックすると設定を確認することができます。

Python Docstring Generator 設定

以下のAuto Docstring: Docstring Formatの部分がフォーマットに関する設定になります。

Python Docstring Generator
Auto Docstring: Docstring Format

プルダウンをクリックして見ると以下のように結構たくさんの種類がありますね。自分の好みやプロジェクトの方針により設定を変更して使用してください。

Python Docstring Generator
Auto Docstring: Docstring Format

どのスタイルを使うのがよいのかという話があるかと思います。numpyスタイルか、googleスタイルかといったあたりがよく話が上がるような気がしますが、プロジェクトとして一貫していればいずれのフォーマットでも問題ないかと思います。

まとめ

VSCodeでのPython開発でdocstringを自動生成してくれるPython Docstring Generatorについて紹介しました。

Python Docstring Generatorのインストール、基本的な使い方、スタイルの設定について説明しています。docstringの記載は関数等の説明を利用者やプロジェクトメンバに伝える意味でも、プログラミングにおいて重要なことであると思っています。

ゼロから自分で書くのは少し面倒ですので、Python Docstring Generatorを活用して効率よく記載していってもらえるとよいかと思います。