Pythonのスタイルガイドの確認

自分の確認用です.

スタイルガイド

スタイルガイドは、出版物などにおいて統一した言葉遣いを規定する手引き (出典:スタイルガイド - Wikipedia

コーディングにおいても, 基本的な書き方のルールをある程度定めることで理解しやすいコードになりうる. いくつか種類が存在する.

PEP-8

Google Python Style Guide

Google Python Style Guide

django

Coding style | Django documentation | Django

既存のコードに対するpep8の確認

pep8

hogehoge.pyをコマンドライン上で確認するには,

$pip install pep8  
$pep8 --show-source hogehoge.py  

などとする.

flake8

flake8リポジトリ

flake8を用いても同様に確認できる.

pip install flake8  
flake8 hogehoge.py  

参考:vscodeでの使用( using-flake8-in-vscode

autopep8

autopep8

autopep8を用いることで, タブをインデントに置換するなど簡単な規約違反は自動で取り除くことができる.

pip install autopep8  
autopep8 -i url.py  

docstringのフォーマット

関数やクラスを説明するコメント文を docstringと呼び, これについてもいくつかの流儀がある.

代表的なものは PEP257, numpy, google のフォーマット.

pandasなどはnumpyフォーマットを採用している. docstringを記述すれば sphinx 等からドキュメントを簡単に出力することができる. vscodeやatomにはdocstringのテンプレートを書きこむプラグインが存在するので, プロジェクトのルールに合わせてプラグインを使用する.

参考:vscodeプラグイン例, autodocstring

各スタイルガイド要約

読みながらの留め書きです, 詳しくは公式のドキュメントを参照してください.

スタイルガイドよりもプロジェクトやチーム内部でのルールが優先されます(コードを読む人たちが慣れ親しんだ規則で書くのが最も読みやすい).

PEP8

GitHub - mumumu/pep8-ja: PEP8 日本語版 参照.

  • インデント
    • インデントはタブかスペースで統一, スペース4回が良い
    • 関数呼び出しの途中で改行する場合は ( の位置にインデントをそろえる
    • 引数の一つ目から改行を入れるならばそろえなくても良い
    • +/- などの二項演算子が長い場合は演算子の手前に改行を入れて演算子の位置を統一する
    • リストの閉じ括弧のインデント方法は2種類
  • 条件分岐
    • if文の条件内部では ( の位置からさらにインデントを入れても良い
    • len(list)==0 ではなく空の場合は False になることを利用する
    • x == Trueなど真偽値を比較しない
    • オブジェクトの型比較は isinstance(insA, insB) を用いる
  • 文字・空行・空白
    • コードは一行あたり最大79文字
    • コメントは一行あたり最大72文字
    • クラスと関数定義の始まり手前には2行空白を入れる
    • クラス内の関数定義の手前には1行空白を入れる
    • 関数に複数のまとまりが存在するならば2行以上空白を入れてもいいが, 多用しない
    • ,, :, ; の直後には空白が来るが, スライスの指定時には空白を入れなくても良い (list[:10] など)
    • 二項演算子は演算子の両側に一つだけスペースが入る
    • 代入演算子(=)の場合はインデントをそろえない
    • デフォルトパラメータを指定する(=)の場合はスペースを入れない ( def foo(param=0) など )
    • 関数アノテーション(->)の前後にはスペースを入れる
  • 変数名
    • モジュール名:すべて小文字
    • パッケージ名:すべて小文字
    • クラス名:CapWords
    • 関数名:mixedCase / すべて小文字
    • 例外名:CapWords
    • 定数:すべて大文字
    • 関数引数:インスタンスメソッドは self, クラスメソッドは cls をはじめに呼ぶ
    • 他、変数名が重複する場合はアンダースコアのルールを適用する
    • l, o, I は見間違うので変数としては使用しない
  • アンダースコア(命名規則の項目参照
    • 変数前にアンダースコア:クラス・モジュール内部でのみ使用する変数
      • モジュール内のグローバル変数には付与する必要あり
      • from XXX import *とした時に読み込まれないようになるが, import XXX では呼ばれる
    • 変数後にアンダースコア:キーワードと衝突しうる変数名の場合に付ける
    • 変数前にアンダースコア2つ:マングリング(内部的には変数名を変更)を行う. クラス間でメソッド名重複が発生した場合に使用.
    • 変数前にアンダースコア2つ, 変数後にアンダースコア2つ:通常は追加で定義しない
    • アンダースコア2つは dunders と呼ぶこともある
  • コメント
    • # を用いたコメントのインデントはコメントを付けるコードのインデントに合わせる
    • インラインのコメント(コードと同じ行にするコメント)ではコードとの間に2つ以上のスペースを置く
    • docstringフォーマットはプロジェクト・チーム内で統一する
  • import
    • 一つの行で異なるモジュールをimportしない (import numpy, scipy など)
    • 同じパッケージから複数のモジュールをインポートする場合は , で複数importして良い
    • import にワイルドカードは使用しない
  • その他
    • エンコードは utf-8
    • 文字列にて, "` は統一されているならばどちらを用いても良い
    • 拡張比較メソッドは全て定義する

Google

google/styleguide 参照.

  • pychecker
  • import
    • 相対パスでのインポートはしない, 同じパッケージが複数回インポートされることを防ぐ
    • モジュール名が長すぎる場合は as を用いて短くする
  • exception
    • Pythonのビルトインのクラスである Exception を継承して独自の例外を定義する
    • 最も上位のブロック以外では except: を使わずに定義した例外を使用する
    • try~exception~ 内部のコードは可能な限り短くする
    • 必要ならば finally を用いて try内部での処理のクリーンアップを行う
  • リスト
    • リストの内包表現は簡単なもののみ利用し, 複雑な場合はループ式で記述する
  • ライセンス
    • 著作権表記は必ず記述する
    • ファイルの原作者名を記述する
    • ライセンス文をライセンスに応じて記述する
  • 変数名
    • クラス、例外:CapWords
    • グローバル定数・クラス内定数:アンダースコア区切りの大文字
    • グローバル変数・クラス内変数:アンダースコア区切りの小文字
    • その他:アンダースコア区切りの小文字
  • その他
    • λ式はワンライナーの場合のみ使用する
    • イテレータ内部ではコンテナを変更しない
    • 標準のイテレータが存在するならば, それを利用する
    • stringモジュールを使用することを避け, stringメソッドを使用する
    • メタクラス, オブジェクトの親の変更など Python の一部の機能は使用を避ける
    • バックスラッシュによる改行は使用しない
    • TODOコメントのフォーマットはそろえる, 何日までに修正するなどは指定があるならば明記する

参考文献