Visual Studio CodeにPython Docstring Generatorを入れて自動でDocstringを書く
概要
昔書いた関数を見返してこれ何をやってるんだ?となることが私はよくあります……それを無くす解決策としてDocstirngなるものを知り,見よう見まねで書いていたんですが面倒くさい……今回VSCodeでDocstirngのテンプレートを自動で補完してくれる拡張機能Python Docstring Generatorを知ったので紹介します.
https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring
導入
この拡張機能を導入するのは非常に簡単です.左の拡張機能タブをクリック,もしくはCtrl+Shift+Xによって拡張機能のマーケットプレイスを開き,docstringと検索を書けることで出てきます.それのインストールをクリックすることでインストールされます.(この画像は既にインストールされている状態なので他の拡張機能にはあるインストールボタンがPython Docstring Generatorにはありません.)
機能
例として整数aとbを引数にとりa**bを返す関数を用意します.
この関数のすぐ下(def~の次の行)に,"を3回入力すると,元々のVSCodeの機能で"が6つ追加されるのですが,更に追加で
このような入力補完が出てきます.これを押すと
このようなDocstringが自動的に出てきます.関数の要約,引数の取る型とその内容,返り値の型とその内容を書き込めます.すごい便利ですね.
Docstringの定型にもいろいろパターンがあり,設定から4つのパターンを選ぶ事が出来ます.
デフォルトではgoogleが使っているスタイルのDocstirngが設定されているようです.他のパターンも実行してみます.
- docblockr
- sphinx
- numpy
どれを選ぶべきなのかはチームで使っている物に合わせたり個人の好みで選ぶのがいいのかなと思います.私はgoogleのパターンを使っていこうと思います.
今回の例で実際に書くとこんな感じでしょうか
(関数化するまでもない単純な処理だというのは置いといて)この関数が何をしているのかすぐ分かるような内容になりました.実際のコードを読まずともこのDocstirngだけを見れば使い方が分かってすぐ利用出来るというのは,まさしく関数化の目的に合致していて良いですね.
複雑な内容の関数だとこのDocstirngの内容もどう書けば分かりやすい内容になるのか,まだ私には分かりませんが色々試行錯誤して見やすいコードを実現していきます.