VS Code コーディング規約を快適に守る

規約とツールでコードの品質を上げる

コーディング規約をチームで共有するとコードの可読性が上がる。
たとえばPEP8はPython標準ライブラリ用のコーディング規約で
1行の文字数を79文字以下とするなどその内容は多岐にわたる。

コーディング規約は学習・運用コストがかかるためLinter・Formatterなどのツールを有効活用したい。
以下、Visual Studio Code（VS Code）用のお勧めの規約・ツールを導入する手順を示す。

概要

Linterツール flake8、Formatterツール autopep8、
docstring支援の拡張機能autoDocstringをインストールし、下の設定を行う。
前提としてMicrosoft公式の拡張機能Pythonは導入済みとする。

setting.json抜粋

    "files.autoSave": "afterDelay",
    "files.autoSaveDelay": 1000,
    "python.linting.lintOnSave": true,
    "python.linting.pylintEnabled": false,
    "python.linting.pep8Enabled": false,
    "python.linting.flake8Enabled": true,
    "python.linting.flake8Args": [
        "--ignore=W293, W504",
        "--max-line-length=150",
        "--max-complexity=20"
    ],
    "python.formatting.provider": "autopep8",
    "python.formatting.autopep8Args": [
        "--aggressive", "--aggressive",
    ],
    "autoDocstring.docstringFormat": "google",

Linter

Linterはコードを静的に解析し、コーディング規約に則っているかチェックするツール。
拡張機能Python導入済みならば標準で使える。

Linterを有効にすればコーディング規約違反のエラー・警告を表示してくれる。

導入方法

PEP8に加えて、論理エラーの検出も行うflake8をインストール。
（論理エラーは「不要なimport」など）

pip install flake8 

ユーザー設定JSON（%AppData%\Code\User\settings.json）に下から取捨選択して追記する。

標準のpylintをオフにし、PEP8をオン。

    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,    

1秒ごとに自動保存して、その度に構文チェック。

    "files.autoSave": "afterDelay",
    "files.autoSaveDelay": 1000,
    "python.linting.lintOnSave": true,

空行に空白が含まれるとWarningになるW293は、エディタの自動インデントが引っかかるのでオフ。
+などのオペレータの後で改行するとWarningになるW504もオフ。

    "python.linting.flake8Args": [
        "--ignore=W293, W504",
    ],

1行の最大文字数はデフォルト80文字（PEP8準拠）。
画面サイズなどにもよるためチームで相談して適宜設定する。

    "python.linting.flake8Args": [
        "--max-line-length=150",
    ],

エラーの種別

• E***: pep8の規約違反
  • 100系 ... インデント（indentation）
  • 200系 ... 空白（whitespace）
  • 300系 ... 空行（blank lines）
  • 400系 ... インポート（imports）
  • 500系 ... 行の長さ（line length）
  • 600系 ... 廃止予定（deprecation）
  • 700系 ... 文（statements）
  • 900系 ... 文法違反（syntax errors）
• W***: pep8の警告
• F***: PyFlakesの論理違反・警告

参考：PythonソースがPEP8スタイルガイドに準じているかをpycodestyleで検査

循環的複雑度

循環的複雑度(Cyclomatic complexity)は分岐の多さを表す指標である。
具体的にはifやfor, switch caseの数+1。大きいほど可読性が下がり、テストケースが増える。
一般には25を越えると本人しか読めないコードになる。

flake8には関数ごとに循環的複雑度を警告するオプションがある。

    "python.linting.flake8Args": [
        "--max-complexity=20"
    ],

使用方法

上の設定なら自動保存され、自動的にLinterが走る。
警告の抑制や変更を行う場合はチームで共有すること。

Formatter

Formatterはコーディング規約に従うように整形（format）するツール。
拡張機能Python導入済みならば標準で使える。

導入方法

autopep8をインストール。

pip install autopep8

ユーザー設定JSON（%AppData%\Code\User\settings.json）で下になっているのをチェック。

    "python.formatting.provider": "autopep8",

標準では空白を調整するフォーマッティングしかしないが、setting.jsonに下を追記すると
a == None を a is None に書き換えるような、より積極的なフォーマッティングを行う。

    "python.formatting.autopep8Args": [
        "--aggressive", "--aggressive",
    ],

上の設定はaggressiveを2回指定し、aggressiveレベル2にしている。

使用方法

選択範囲を右クリックして選択範囲のフォーマットなど。

docstring

関数などの説明をするdocstringのスタイルもプロジェクトで揃える必要があり
autoDocstringというVS Codeの拡張機能をいれると運用しやすい。
参照に関しては、拡張機能Python導入済みなら標準でツールチップ表示してくれる。

Googleスタイルのdocstring

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1

    Returns:
        bool: Description of return value
    """
    return True

導入方法

拡張機能autoDocstringをインストール。

メニューのファイル > 基本設定 > 設定 から autoDocstringで絞り込んで、
Auto Docstring: Docstring Formatをgoogleに変更。

使用方法

下のどれかの操作でdocstring生成。tabキーで次の項目に移る。

• Ctrl + Shift + 2キー
• """を入力してEnterキー
• 右クリックしてGenerate Docstring

その他

命名規則

Linterは命名規則をチェックしない。
言語的にも制約はないが、標準ライブラリとの整合性を考えるなら統一することが望ましい。
PEP8の命名規則はsnake_case、PascalCase、SNAKE_CASEの3種類である。

対象	規則	備考
パッケージ	snake_case	アンダースコアなしを推奨
モジュール	snake_case	アンダースコアなしを推奨
クラス	PascalCase
例外	PascalCase
クラス変数	PascalCase
メソッド	snake_case	内部メソッドは頭にアンダースコア
引数	snake_case	予約語と被るときは末尾にアンダースコア
変数	snake_case	内部変数は頭にアンダースコア
定数	SNAKE_CASE