初めに
実用として使用しているエディタ(VSCode)での拡張機能によるdcstring生成補助をさらりと紹介する。
自身の関連記事
・docstringのスタイルと書き方。（2021/01/30）
[Python] docstringのスタイルと書き方
・VSCodeでのdocstring生成に関する機能拡張。（2021/02/01）←本記事
[Python] VSCodeでのdocstring生成拡張
・docstringを利用した関数テスト。（2021/02/07）
[Python] 関数のテストとその手法概要（dcstest, unittest, pytest）
VSCode
大人気のエディタ。説明を引用します。
Visual Studio CodeはMicrosoftが開発しているWindows、Linux、macOS用のソースコードエディタである。
デバッグ、埋め込みGitコントロールとGitHub、シンタックスハイライト、インテリジェントなコード補完 、スニペット、コードリファクタリングのサポートが含まれる。
カスタマイズ性が高く、テーマやキーボードショートカット、環境設定を変更できたり、機能を追加する拡張機能をインストールすることができる。
ソースコードはフリーでオープンソースで、寛容なMITライセンスの下でリリースされている。
コンパイルされたバイナリはフリーウェアである。
Stack Overflow 2019 Developer Surveyでは、Visual Studio Codeが最も人気のある開発者環境ツールとしてランクインし、87,317人の回答者のうち50.7%が使用していると回答した。
@wiki
非プログラミングエンジニアとしては、開発環境は jupyter notebookの方が実用上便利なケースが多い。
ただ、コードが大規模になったりプロジェクトとしての運用が見込まれる場合は即座にエディタ移行したほうがいいと思っている。
VSCodeでも jupyter notebookの形式に対応した拡張機能などあるが、それは別の話。。。
Python Docstring Generator
VSCodeでの拡張機能。Pythonのdocstringを生成する拡張である。
紹介する拡張機能は関数に対して自動生成を行うが、クラスに対してはサポートがなかった。
Automatically generates detailed docstrings for python functions
既定スタイルはGoogleスタイルとなっている。
なお、スタイルは機能の設定(歯車)の [ 拡張機能の設定 ] → [ Auto Docstring: Docstring Format ] から選択可能である。
以下のコード (サンプルなので意味は特にない) に対して、自動生成したものを以降に示す。
def func(arg1, arg2:int, arg3 = 1):
# ここで"""を入力した際に生成。
result = int(arg1) + int(arg2) + int(arg3)
if result > 100:
raise TypeError
return result
reStructuredTextスタイル (Sphinx)
def func(arg1, arg2:int, arg3 = 1):
"""[summary]
:param arg1: [description]
:type arg1: [type]
:param arg2: [description]
:type arg2: int
:param arg3: [description], defaults to 1
:type arg3: int, optional
:raises TypeError: [description]
:return: [description]
:rtype: [type]
"""
result = int(arg1) + int(arg2) + int(arg3)
if result > 100:
raise TypeError
return result
Googleスタイル
def func(arg1, arg2:int, arg3 = 1):
"""[summary]
Args:
arg1 ([type]): [description]
arg2 (int): [description]
arg3 (int, optional): [description]. Defaults to 1.
Raises:
TypeError: [description]
Returns:
[type]: [description]
"""
result = int(arg1) + int(arg2) + int(arg3)
if result > 100:
raise TypeError
return result
NumPyスタイル
def func(arg1, arg2:int, arg3 = 1):
"""[summary]
Parameters
----------
arg1 : [type]
[description]
arg2 : int
[description]
arg3 : int, optional
[description], by default 1
Returns
-------
[type]
[description]
Raises
------
TypeError
[description]
"""
result = int(arg1) + int(arg2) + int(arg3)
if result > 100:
raise TypeError
return result
最後に
今までは何の気なしにreStructuredTextスタイルを使用していたが、
比較すると行数や密度の差による見易さの差がよくわかった。
参考・引用
[ 自身の記事 ]
[Python] docstringのスタイルと書き方
[ VSCode ]
VSCode公式