Zenn
🐢

【Python】VSCode拡張機能で自信をもってコーディングする方法！

2024/02/17に公開
Python
VS Code
VS Code 拡張機能
pylint
yapf
tech

プログラミングで、自分の書いたコードに自信が持てないことってありませんか？
他人にコードを見せることが恥ずかしくて嫌だという経験、あるのではないでしょうか。

私も以前はそうでした。

コードが汚いと思われたり、能力が低いと思われたりするのではないかと不安になり、また自らの内面をさらけ出すようで何とも恥ずかしいものでした。

しかし、プログラミング能力向上にとって、コードを他人に見せてフィードバックを受けることは大切です。

そこで試していただきたいのが、VSCodeエディタと拡張機能を使う方法です。コードのエラーチェック、整形、補完などを拡張機能によって自動でできるので、読みやすさや品質を高めることが簡単にできます。

今回は、Pythonのコーディングに役立つ拡張機能をいくつか紹介します。
それぞれの拡張機能のインストールや設定方法、使い方のポイントなどを詳しく説明します。

ブログ対象者

  • 自分のコードの読みやすさや品質に自信が持てない方
  • コードのレビューやテストを行う、チームで開発するなど、コードの読みやすさや品質を高める必要がある方
  • Pythonを扱う方
    説明をPython言語で行うため。ただし、他の言語でも似たような仕組みがありますので、本ブログで雰囲気は感じ取っていただけると思います。

得られる効果

このブログを読むことで、次のような効果が得られます。

  • Pythonのコーディングルールに準拠し、読みやすいコードを作成できるようになります。
  • コードのエラーチェックや整形、補完などを自動で行う環境を構築でき、コードの品質を高めることができます。
  • 他人にコードを見せることが苦にならなくなり、フィードバックを受けやすくなることで、能力向上が期待できます。

これらの効果により、自信をもってコーディングができるようになります！

環境の準備

コーディングするとき、VSCodeはとても便利なエディタですが、標準の機能だけではコードを効率的に書くことができません。そこで、VSCodeには様々な機能を追加できる拡張機能というものがあり、これをインストールして使用します。さらに、それらを便利に使うための設定を行います。

それでは早速、環境の準備に取りかかりましょう。

① 拡張機能のインストール

次の図に示す6つの拡張機能を使います。それぞれの拡張機能の機能概要は、図に整理していますので、簡単に眺めてみてください。まずこれらをインストールしていきます。似たような名前の拡張機能もありますので、拡張機能や作者の名前を正しく確認して、作業を行ってください。

ext_list.png
自信をもってコーディングするための拡張機能一覧

上記は、画像として表示されていますので、拡張名をコピー&ペーストしてミスなく検索できるように、以下にテキストを用意しました。ご活用ください。

Pylint, Pylance, Mypy Type Checker, yapf, isort, autoDocstring

もし、拡張機能のインストール方法がわからない場合は、以前私が書いた次の記事を参考にしてみてください。

https://zenn.dev/safubuki/articles/turtle-20240121-vscode#拡張機能：インストール方法

② Google Style Guides ダウンロード・編集

Google Style Guidesとは

Google Style Guidesとは、Googleが公開しているプログラミング言語ごとのコーディングスタイルガイドのことです。これらのガイドは、Googleのコードの品質や可読性を高めるために作られたもので、世界中の開発者から高い評価を得ています。私は、Googleの人や、関連サービスを作っている人たちと同じスタイルで、記述することができるというのは、とても素敵なことだと思います😊Pythonの場合、Pylint向けの設定ファイルとして提供されており、ダウンロードして使うことができます。

ダウンロードの手順

  1. 次のサイトにアクセスします。

https://google.github.io/styleguide/

  1. 各種言語のスタイルガイドがあります。
    今回はPythonを対象にしますのでPython Style Guideのリンクをクリックします。

py_style
Google Style Guidesのページ

  1. 2.1 Lintのpylintrcのリンクをクリックします。
    すると、ファイルのダウンロードが始まります。

py_style_py
Google Python Style Guideのページ

  1. ダウンロードしたpylintrcファイルを次の場所に移動します。
    なお、{ユーザー名}は、自身の環境にあわせて書き換えてください。
    C:\Users\{ユーザー名}\AppData\Roaming\Code\User

編集の手順

  1. pylintrcをVSCodeなどのエディタで開き、次の項目を編集します。

    • max-line-length
      1行あたりの最大文字数
      PEP8に従うなら1行は79文字ですから、無理して変更する必要はないです。が、プロジェクトの規約や個人の好みによっては変更したいというケースもあるでしょうから、ここでは変更しています。
      ※ちなみに79文字制限なのに設定値が「80」になっているのは、改行文字も含まれるからです。PEP8の79文字に改行文字は含まれません。
      pylintrc 240行目付近
      + max-line-length=100
- max-line-length=80
    • indent-string
      インデントのスペース数
      一般的には4スペースなのですが、Googleのスタイルガイドでは2スペースになっているため、4スペースに変更します。
      pylintrc 260行目付近
      + indent-string='    '
- indent-string='  '

  2. 編集したpylintrcファイルを保存したら、この項目の作業は完了です。

③ VSCodeの設定（Settings.json）

続いてVSCodeの設定を行います。
この設定が終わると、すべての設定は完了します。あともう少し頑張ってください。

  1. Ctrl + Shift + pを入力し、コマンドパレットを表示します。

  2. 入力欄に「setting」と入力し、候補の中からPreferences: Open User Settings(JSON)を選択します。するとsettings.jsonというファイルが開きます。

  3. 次の内容をsettings.jsonにコピー＆ペーストしてください。

    settings.jsonにコピーする内容
    {
    "[python]": {
        "editor.insertSpaces": true,
        "editor.tabSize": 4,
        "editor.defaultFormatter": "eeyore.yapf",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit",
        }
    },
    "pylint.args": [
        "--rcfile=C:\\Users\\{ユーザー名}\\AppData\\Roaming\\Code\\User\\pylintrc"
    ],
    "yapf.args": [
        "--style",
        "{based_on_style: google, column_limit: 100, indent_width: 4}"
    ],
    "mypy-type-checker.args": [
        "--ignore-missing-imports",
        "--follow-import=silent",
        "--check-untyped-defs"
    ]
}

    それぞれの設定項目の意味は次の通りです。

    • "[python]"：python言語に対する設定
      • "editor.insertSpaces"：
        タブキーを押したときに、スペースを挿入します
      • "editor.tabSize"：
        タブのサイズを 4スペース に設定します
      • "editor.defaultFormatter"：
        デフォルトのフォーマッタとして yapf を使用します
      • "editor.formatOnSave"：
        ファイルを保存する際に自動的にフォーマットを行います
      • "editor.codeActionsOnSave"：
        ファイルを保存する際にコードアクションを実行します
        • "source.organizeImports"：
          ファイルの先頭にあるインポート文を整理します
    • "pylint.args"：pylintの設定
      先ほどダウンロード・編集したpylintrcファイルを設定ファイルとして使います
    • "yapf.args"：yapfの設定
      Googleのスタイルガイドに基づき、コード幅を100 、インデント幅を4にします
    • "mypy-type-checker.args"：mypyの設定
      • "--ignore-missing-imports"：
        インポートされたモジュールが見つからない場合でもエラーを無視します
        ※ 外部ライブラリが存在しない場合でも型チェックを続行するために行います。
      • "--follow-import=silent"：
        インポートされたモジュールの型チェックを行わず、静かに無視します
        ※ 型チェックのパフォーマンス向上のために行います。
      • "--check-untyped-defs"：
        型が明示されていない関数定義もチェックします

  4. 設定が完了したら、ファイルを保存して閉じてください。

  5. Ctrl + Shift + pを入力し、コマンドパレットを表示します。

  6. 入力欄に「reload」と入力し、候補の中からDeveloper: Reload Windowを選択します。

  7. 画面が更新されたら完了です。

以上で全ての環境設定は完了です。お疲れさまでした🎉
これで、あなたは自信をもってコーディングをするスタートラインに立ちました！

効果を体感しよう

ここからは、拡張機能の効果を体感します。
悪いコードの例を示しますので、それが拡張機能を駆使してどのように改善していくか、自身の環境で確かめてみてください。

悪いコード降臨

私がAIと協力しながら作成した、サンプルコードを以下に示します。お世辞にも良いとは言えない、悪いコードの例になります。コード上には、青や黄、赤などの線で多くの警告やエラーが表示されています。これらは拡張機能が全て指摘しています。この警告やエラーを無くすことが、きれいなコードを書くポイントになってきます。

ext_sample
悪いコードのエラー確認gif動画

悪いところが多々ありますが、プログラムとしては意図したとおりに動作します。

ext_execute
プログラムの実行結果

悪いコードをキレイに

それでは、先ほど降臨した悪いコードをキレイにしていきます。
実際に皆さんの環境でもできるように、一つ一つ手順を示します。

  1. VSCodeの開発環境にsample.pyという空のファイルを作成します。
  2. 次の悪いコードをコピーして、sample.pyにペーストします。
sample.py（これをコピーしてください）
from typing import List
import random
import math

def g_rand() -> List[int]:
  num_list = []
  for i in range(5):
      num_list.append(random.randint(1, 100))
  return num_list

def g_sums(numbers: List[int]) -> int:
  total = 0
  for n in numbers:
      total += n
  return total

def p_res(prt_numbers: int, prt_total: List[int]) -> None:
    print("The random numbers are:", prt_numbers)
    print("The sum is:", prt_total)

if __name__ == "__main__":
    numbers = g_rand()
    total = g_sums(numbers)
    p_res(numbers, total)
  1. 画面を注意深く見つめながらCtrl + sを入力してファイルを保存します。
    この時、コードに変化が起こったと思います。
    もし、見逃した方はCtrl + zで戻して、再びCtrl + sしてみてください。
    これは、yapf、isortの働きによりコードが自動的に整形されたのです。
    yapfはコードのインデントや改行などのスタイルを、isortはインポートの順序を自動で整えました。yapfは、この他にも1行あたりの文字数が99文字を超えていた場合、範囲内に収まるように適切に改行します。
sample.py（yapfとisortによる自動整形後）
import math
import random
from typing import List


def g_rand() -> List[int]:
    num_list = []
    for i in range(5):
        num_list.append(random.randint(1, 100))
    return num_list


def g_sums(numbers: List[int]) -> int:
    total = 0
    for n in numbers:
        total += n
    return total


def p_res(prt_numbers: int, prt_total: List[int]) -> None:
    print("The random numbers are:", prt_numbers)
    print("The sum is:", prt_total)


if __name__ == "__main__":
    numbers = g_rand()
    total = g_sums(numbers)
    p_res(numbers, total)

format
フォーマッタの効果(yapf, isort)

  1. Pylint、Pylance、mypyの指摘を修正します。
    手順3までの対応で形は整いましたが、まだエラーは残っています。ここではその改善をしていきます。まず、1行目のimport mathに指摘があります。マウスカーソルを当てると次のような表示が出力されます。
    shiteki
    拡張機能による指摘
    mathモジュールが処理の中で使用されておらず、不要のようです。今回はこのメッセージの一文だけで指摘内容が分かりますが、場合によっては内容を理解できないことがあります。その時は、赤線の青い文字をクリックしてみてください。すると、次のようなWebページに移動します。
    pylint_page
    Pylintドキュメンテーションサイト
    このページはPylintのドキュメンテーションをまとめたページで、問題のあるコードと正しいコードをサンプルを交えながら解説しています。指摘内容の理解と改善に役立ちます。さらに便利なのがQuick Fixです。以下の赤線の青文字をクリックします。
    quick_fix
    Quick fix
    すると、次のような表示がされます。この中からRemove unused importsを選択すると使っていないimportが削除されます。all unusedを選択すると全ての使っていないimportが削除されます。ただし、このQuick Fix、指摘内容によっては使えないことがあります。その場合は、先ほどのページなどを確認しながら手動で修正を行います。
    quick_fix_sel
    Quick fix選択画面
    残りのエラーや警告も同じように修正をしていきます。
    手順4が完了すると一通りのエラーは無くなります。頑張ってください💪

  2. 関数コメントで、さらに分かりやすくします。
    ここでは、autoDocstringという拡張機能を使って、関数コメントのひな型を自動で生成する方法を紹介します。次のように"(ダブルクォーテーション)を3回入力するだけで、関数コメントの概要、引数、戻り値のひな型を作ってくれます。
    docstring
    関数コメント(docstring)のひな型生成
    あとは、このひな形に説明文を記述していきます。完成すると次のような形になります。
    func_comment
    関数コメント(docstring)
    関数のコメントについて、関数名の上に#コメントで記述するケースを見かけますがこれはオススメしません。一般的な方法ではないですし、ヒント機能で関数コメントの内容が表示されないからです。ヒント機能は次のように、マウスカーソルをコールする関数に当てるとその内容が表示される機能です。
    hint
    ヒント機能
    せっかく書いたコメントをよりよく活用するために、ぜひこのスタイルでコメントを書いてみてください。

  3. 関数名も分かりやすい名称に修正します。
    g_rand、g_sums、p_resは、パッとみて関数名が分かりにくいと感じる方もいると思いますので、get_random_numbers、get_sum、print_resultに修正します。
    関数名や変数名は、プロジェクトによっては命名ルールが決まっている場合がありますので、その際はプロジェクトのルール等に従ってください。

完成後のコードは次のようになります。

sample.py（最終完成版）
"""ランダムな数値を生成して、それらを加算、出力する"""

import random
from typing import List


def get_random_numbers() -> List[int]:
    """1から100までのランダムな整数を5つ生成し、それらをリストとして返す関数。

    Returns:
        List[int]: 生成されたランダムな整数のリスト
    """
    num_list = []
    for _ in range(5):
        num_list.append(random.randint(1, 100))
    return num_list


def get_sum(number_list: List[int]) -> int:
    """整数のリストを引数として受け取り、その合計値を返す関数。

    Args:
        number_list (List[int]): 合計値を求める整数のリスト

    Returns:
        int: リストの合計値
    """
    sum_total = 0
    for n in number_list:
        sum_total += n
    return sum_total


def print_result(prt_numbers: List[int], prt_total: int) -> None:
    """ランダムな整数のリストとその合計値を引数として受け取り、それらを出力する関数。

    Args:
        prt_numbers (List[int]): 出力するランダムな整数のリスト
        prt_total (int): 出力する合計値
    """
    print("The random numbers are:", prt_numbers)
    print("The sum is:", prt_total)


if __name__ == "__main__":
    numbers = get_random_numbers()
    total = get_sum(numbers)
    print_result(numbers, total)

以上で全て完了となります！お疲れさまでした🎉

まとめ

いかがでしたでしょうか？
VSCodeと拡張機能を使って、Pythonのコーディングルールに準拠し、読みやすいコードを作成できるようになりました。また、コードのエラーチェックや整形、補完などを自動で行う環境を構築することができました。

このようにPEP 8やGoogle Style Guideなどのコーディング規約に準拠したコーディングを行うと「自分はコーディングを世の中のエンジニアと同じようにできているんだ！」「細かなミスもなく、品質を保てている！」と思えるようになり、自分のコーディングに自信が湧いてきます。そして、他人にコードを見せることが苦にならなくなり、フィードバックもどんどん受けられるようになります。
また、フィードバックをする側もフィードバックをしやすくなり、細かなミスの指摘ではなく、ロジックなど本質的な部分の指摘ができるようになります。

このページを読んでくださった方が、少しでも自信をもってコーディングすることができるようになった、あるいはその気持ちになっていただけたなら幸いです。最後までお付き合いくださり、ありがとうございました。

リンク

私は、この記事に書いた方法で自信をもってコーディングできるようになりました👍
そして、今年さらに一歩踏み出してOSSの開発にチャレンジして、GitHubに公開してみました。
もちろん、この記事で紹介した内容は全て実践しています。
小さいプログラムで、まだまだ駆け出しではありますが、スター(GitHubのイイねみたいなやつ)をいただけるのは最高の喜びです。私にとって一つ一つは重く、価値のあるスターです🌟

もしよければ、そのOSSについてまとめた記事とGitHub見てみていただけると嬉しいです。

https://zenn.dev/safubuki/articles/turtle-20240128-stable-ext

https://github.com/safubuki/sd-webui-latent-regional-helper

更新履歴

  • 2024/03/02
    ブレークタイム「Quick FixのFix using CopilotとExplain using Copilotとは？」の項目に私が書いたGitHub Copilotの記事のリンクを追加しました。

  • 2024/08/03
    ③ VSCodeの設定（Settings.json）の設定内容を見直し、説明文を追加修正しました。
    「おまけ」という章タイトルを「リンク」に変更しました。

GitHubで編集を提案

Discussion