この記事は、ジーズアカデミー 技術記事書いてみた編 Advent Calendar 2023の11日目の記事です。
今週、だいぶ空きがあったので、アドベントカレンダージャック中です。笑
せっかくなので、G’s ACADEMYの卒業制作でもふんだんに使用したFast API（Python）をさらにモノにすべく、Fast API（Python）のアウトプット→自分の学びに転化させていただくのに使わせていただきます！
Pythonでは、Docstringというものでクラスや関数に関する説明を記載するためのコメント形式・表記があります。
今回の記事では、Docstringの基礎と、VSCode環境で手軽にDocstringを挿入する方法についての記事を書いてみたいと思います！
目次
PythonのDocstringとは？？
先ほども触れさせていただきましたが、PythonのDocstringはJavaScript開発でいうJSDocsのような、Pythonにおけるクラスや関数に関する説明を記載するためのコメント形式・表記です。
書き方はいたってシンプル！例えば、Pythonの関数に対してDocstringを設定してみます！
from pptx import Presentation
def load_pptx(file):
"""
アップロードされたPPTXファイルを読み込み、Presentationオブジェクトを返す。
この関数は、アップロードされたファイルを一時的にディスクに保存し、
python-pptxライブラリを使用してPresentationオブジェクトに変換します。
Args:
file (UploadFile): FastAPIのUploadFileオブジェクト。アップロードされたPPTXファイル。
Returns:
Presentation: python-pptxライブラリのPresentationオブジェクト。
"""
with open(file.filename, "wb") as buffer:
buffer.write(file.file.read())
pptx = Presentation(file.filename)
return pptx今回用意したload_pptx関数は、アップロードされたパワーポイントファイルを、PythonのライブラリであるPython-pptxで用意されているPresentationオブジェクトに変換・返すということをしています。
def load_pptxの直下に諸々コメントが書かれていますが、この部分がDocstringで表現された関数の説明です！
- トリプルクォート（
'''または"""）を説明の始まりと終わりに記載し、その中に関数の説明などコメントを書いていく。 - 記載する内容としては「関数やクラスの説明」「引数の説明」「関数であれば戻り値が何なのかの説明」あたりを記載する。
ようにするのがDocstringを書く上での基本的なポイントのようです！
PythonのDocstringのスタイル（記述フォーマット）について
Docstringには明確な記述フォーマットが用意されているわけではないようなんですね…。しかし、フォーマットが決まっていないから自由にDocstringを書いていいよ！とはならないわけです。
大規模プロジェクトになればなるほど関わる人が増える可能性が高いで す。そうなった場合、Docstringの記述フォーマットに何らかのルールがないと、プロジェクトメンバー各々が自由にDocstringを書いてしまい、結果としてDocstringの記述内容に対して統一感がなくなり、コメントや説明を残す意味があまりなくなってしまいます。
そこで、Docstringの記述フォーマットを決める上では、世に存在するスタイルを参考にすることも多いようです。
Google Python Style Guideや、numpydoc docstring guideなどが参考にされる代表的なDocstringの記述フォーマットガイドになっています。
あくまで僕の一意見ですが、まずは
- 関数自体が何をしているのかについての説明
- 引数の型定義と説明
- 戻り値の型定義と説明
- その他注意事項
あたりがまずはしっかりと掲載されていれば良いかと考えています！
Google Python Style Guideによれば、例えば関数に対するDocstringであれば
"""関数の説明タイトル
関数についての説明文
Args:
引数の名前 (引数の型): 引数の説明
引数の名前 (:obj:`引数の型`, optional): 引数の説明.
Returns:
戻り値の型: 戻り値の説明 (例 : True なら成功, False なら失敗.)
Yields:
戻り値の型: 戻り値についての説明
Note:
注意事項などを記載
"""といった感じで記載するようです。
VSCodeのプラグイン「Python Docstring Generator」で快適なDocstring環境を作る
さて本題です！そんなPythonのDocstringですが、手打ちでいちいちトリプルクオーテーションや各内容を記述するのもさすがに大変です。
VSCodeのプラグイン「Python Docstring Generator」を使うと、手軽にPythonのDocstringを挿入することができるようになります！
プラグインをVSCodeにインストールすると、Pythonの関数直下でトリプルクオーテーションを記述した時点で「Generate Docstring」というメニューが出てきます。
Generate Docstringメニューを選択すると、自動的にDocstringのフォーマットが挿入されます！
挿入されたフォーマットを見ると
"""_summary_
Args:
pptx (_type_): _description_
Returns:
_type_: _description_
"""上記のような感じになっているのですが、_summary_だったり_description_だったり、アンダーバーで始まりアンダーバーで終わる部分については「自分でしっかりと書いてね！」という部分だととらえていただければOK！
from pptx import Presentation
def load_pptx(file):
"""
アップロードされたPPTXファイルを読み込み、Presentationオブジェクトを返す。
この関数は、アップロードされたファイルを一時的にディスクに保存し、
python-pptxライブラリを使用してPresentationオブジェクトに変換します。
Args:
file (UploadFile): FastAPIのUploadFileオブジェクト。アップロードされたPPTXファイル。
Returns:
Presentation: python-pptxライブラリのPresentationオブジェクト。
"""
with open(file.filename, "wb") as buffer:
buffer.write(file.file.read())
pptx = Presentation(file.filename)
return pptxしっかりと埋めていくと、結果、先ほど掲載したようなDocstringのようなものが誕生します！
ちなみに、Python Docstring Generatorの設定を見てみたところ、デフォルトはGoogle Python Style Guideのフォーマットに基づいた形で出力されるようになっているようです。
まとめ
ということで、今回はPythonのDocstringの基本・VSCode環境で手軽にDocstringを挿入するPython Docstring Generatorについてブログ記事を書いてみましたー！
JSDocsだろうがDocstringだろうが、要するに適切にコメントや説明を書いて、将来の自分や他の人が見てわかりやすい環境を作ることがとっても大事！
そして、わかりやすくコメントや説明を書くためのポイントはどのDocsであろうが同じなんだなぁということを個人的に感じました！
