vscodeでPythonのdocstringを作成する方法を現役エンジニアが解説【初心者向け】

初心者向けにvscodeでPythonのdocstringを作成する方法について現役エンジニアが解説しています。docstringとはPythonの関数やクラスに記述するコメントの事を指します。vscodeの機能を使って簡単に書けるようにautoDocstringをインストールします。

TechAcademyマガジンはオンラインのプログラミングスクールTechAcademy [テックアカデミー]が運営。初心者向けに解説した記事が4,000以上あります。現役エンジニアの方はこちらをご覧ください。

vscodeでPythonのdocstringを作成する方法について、TechAcademyのメンター(現役エンジニア)が実際のコードを使用して、初心者向けに解説します。

Pythonについてそもそもよく分からないという方は、Pythonとは何なのか解説した記事を読むとさらに理解が深まります。

 

なお本記事は、TechAcademyのオンラインブートキャンプ、Python講座の内容をもとに紹介しています。

 

田島悠介

今回は、Pythonに関する内容だね!

大石ゆかり

どういう内容でしょうか?

田島悠介

vscodeでPythonのdocstringを作成する方法について詳しく説明していくね!

大石ゆかり

お願いします!

今回は、vscodeでPythonのdocstringを作成する方法について紹介します。

docstringとは

まずはじめに、docstringとはPythonの関数やクラスに記述するコメントの事を指します。docstringを記述する事で、コードの可読性が向上します。

docstringの基本的な記述ポイントは以下の3点になります。

  1. コメントを複数行のコメントブロック「”””」で囲み、最初の「”””」の右隣にタイトルを記載する
  2. docstringは基本的にimportよりも前に記載する
  3. docstringを記述できるのは、 モジュール、クラス、関数(メソッド)の3つが対象となる

 

docstringの作成に便利なvscodeの拡張機能

ここではdocstringの作成に便利なvscodeの拡張機能「autoDocstring」について紹介します。

導入方法

導入方法は以下の画像を参考に、拡張機能の検索から「autoDocstring」を入力すると出てくるのでそちらをインストールしてください。

VSCODEでautoDocstringをインストールするために、拡張機能の画面の検索ボックスに入力した場面。

Installボタンをクリックし以下のような画面になったらインストール完了です。

VSCODEでautoDocstringをインストールした画面。

初期設定

ここでは先ほどインストールしたautoDocstringを使用して挿入するdocstringのフォーマットを設定します。VScode左下の歯車のマークからSettingsを選択し設定画面を開きます。

VSCODEにインストールしたautoDocstringの設定画面を開くために左下の歯車のマークからSettingsを選択した画面。

設定画面が開いたら、検索欄にautoDocstringと入力し、Auto Docstring: Docstring Formatの部分が表示されますのでリストから任意のフォーマットを指定します。(今回はGoogleを選択しました。)

VSCODEにインストールしたautoDocstringの設定画面で、フォーマットを選択した画面。

以上で、autoDocstringの初期設定は終了です。

[PR] Pythonで挫折しない学習方法を動画で公開中

実際に使ってみよう

それでは、早速「autoDocstring」を使用して実際にdocstringを記述してみましょう。vscodeを起動し、以下のようなサンプルコードを用意します。

このコードはあくまで例としてであり、特に指定はないので自由に設定して大丈夫です。

サンプルコード

def docstring_sample(test):

    pass

 

vscode画面

VSCODEにインストールしたautoDocstringを使うために書く、Pythonのサンプルコード。
vscode画面上で右クリック→GenerateDocstringで自動的にdocstringが挿入されます。

PythonのコードにVSCODEで右クリックしてautoDocstringのGenerateDocstringを選択した画面。

「autoDocstring」を使用してdocstringが挿入された状態が以下の画面になります。

VSCODEのautoDocstringを使って、Pythonのサンプルコードにdocstringを挿入した画面。

挿入されたdocstringに関数の説明や引数の説明を入力します。

VSCODEのautoDocstringを使って、docstringを挿入した後に、関数や引数の説明を入力した画面。

まとめ

今回は、vscodeでPythonのdocstringを作成する方法について紹介しました。

記事冒頭でも述べたように作成したコードにdocstringを挿入する事でコードの可読性が向上します。

過去に作成したプログラムを再度アップデートする際や、プログラムを複数人で開発する際などにdocstringが挿入されていることでコードが読みやすくなり作業をスムーズに行うことができるというようなメリットがありますので、コードを書く際の癖としてしっかり身につけていきましょう。

監修してくれたメンター

菅繕久(すがよしひこ)

現在はフリーランスのエンジニアをしていてプログラミング歴は8年目になります。

普段は Python、FileMaker等を使って様々な業務で活用できるIoTプロダクトRPAツールを作成しています。
開発実績としては、業務自動化ツール(在庫管理・発注・ファイル操作 etc)、電子カルテシステム、ロボット用プログラムなどがあります。
TechAcademyではPythonコースを担当しております。

 

大石ゆかり

内容分かりやすくて良かったです!

田島悠介

ゆかりちゃんも分からないことがあったら質問してね!

大石ゆかり

分かりました。ありがとうございます!

 

TechAcademyでは、初心者でも最短4週間で、Pythonを使った人工知能(AI)や機械学習の基礎を習得できる、オンラインブートキャンプを開催しています。

また、現役エンジニアから学べる無料体験も実施しているので、ぜひ参加してみてください。