Pythonのコーディング規約PEP8を要約してみる(2)

  • 25
    いいね
  • 4
    コメント
この記事は最終更新日から1年以上が経過しています。

Pythonのコーディング規約PEP8を要約してみる(1)
の続き

コメント

ブロックコメント

ブロックコメント(#)は、一般的にその後に続くいくつかのコードに適用され、そのコードと同じレベルにインデントする.

インラインコメント

文とインラインコメントの間は、少なくとも二つのスペースを置く.
自明なことを述べているインラインコメントは不要.

悪い例:
x = x + 1          # xを1増やす

ドキュメンテーション文字列(別名 “docstrings”)

すべてのモジュールや関数、クラス、メソッドにはdocstringを書くべき.

命名規約

一番重要な原則

実装よりも使い方を反映した名前にする

実践されている命名方法

b (小文字1文字)
B (大文字1文字)
lowercase
lower_case_with_underscores
UPPERCASE
UPPER_CASE_WITH_UNDERSCORES
CapitalizedWords

守るべき命名規約

・単一の文字 ‘l’ (小文字のエル)、’O’ (大文字のオー)、’I’(大文字のアイ) を変数として使ってはならない
・モジュールの名前は、全て小文字の短い名前にする
・クラスの名前にはCapWords方式(単語の頭文字を大文字にしてつなげる)を使う
・モジュール内限定グローバル変数は頭にアンダースコア(_)をつけて外部非公開を明示する
・関数の名前は小文字のみにする
・インスタンスメソッドのはじめの引数の名前は常にselfを使う
・クラスメソッドのはじめの引数の名前は常にclsを使う
・メソッド名とインスタンス変数は小文字のみにし、必要に応じて単語をアンダースコアで区切る
・定数は大文字で書き、単語をアンダースコアで区切る

継承の設計

・公開されている(public)属性の先頭にはアンダースコアを付けない
・公開している属性の名前が予約語と衝突する場合は、属性の名前の直後にアンダースコアを追加する
・関数呼び出しの実装をシンプルなデータアクセスの文法で隠すために、プロパティを使う
・サブクラスで使って欲しくない属性があった場合、その名前の最後ではなく、先頭にアンダースコアを二つ付ける

公開インターフェイスと内部インターフェイス

・ドキュメントが明示的に内部インターフェイスだと宣言していない限り、ドキュメント化されたインターフェイスは公開インターフェイスと見なす
・内部インターフェイス(パッケージ、モジュール、クラス、関数、属性、その他の名前) は名前の前にアンダースコアをひとつ付ける

プログラミングに関する推奨事項

・他のPython実装 (PyPy, Jython, IronPython, Cython, Psyco など) で不利にならないようなコードを書く
・Noneと比較をする場合は、常に is か is not を使う
・拡張比較を使って並び替えを実装する場合,全ての演算
(__eq__, __ne__, __lt__, __le__, __gt__, __ge__)
を実装する
・ラムダ式を直接識別子に結びつける代入文を書くのではなくて、常に def 文を使う

良い例:
def f(x): return 2*x
悪い例:
f = lambda x: 2*x

・BaseException ではなくて、 Exception から例外を派生させるようにする
・Python3では、オリジナルの traceback を失わず明示的に例外を入れ替えるために “raise X from Y” を使う
・Python2で例外を発生させる場合、 raise ValueError('message') を使う
・例外をキャッチする時は、例外を指定しない生の except: ではなく、特定の例外を指定する

こんな感じ
try:
    import platform_specific_module
except ImportError:
    platform_specific_module = None

・キャッチした例外を特定の名前に結びつける場合、例外に明示的に名前を付ける

こんな感じ
try:
    process_data()
except Exception as exc:
    raise DataProcessingFailedError(str(exc))

・オペレーティングシステムのエラーをキャッチするときは新しいオペレーティングシステム関連のエラー階層を明示的に使う
・すべての try/except について、try で囲む範囲を必要最小限のコードに限るようにする

良い例:
try:
    value = collection[key]
except KeyError:
    return key_not_found(key)
else:
    return handle_value(value)
悪い例:
try:
    # try で囲む処理が大きすぎる
    return handle_value(collection[key])
except KeyError:
    # handle_value() が発生させる KeyError もキャッチする
    return key_not_found(key)

・リソースがコードの特定の部分だけで使われる場合は with 文を使う
・return文は一貫した書き方をする.
・式を返しているreturn文が関数の中にある場合、値を何も返さないreturn文は 明示的に return None と書く
・stringモジュールよりも、文字列メソッドを使う
・文字列に特定のプレフィックスやサフィックスがついているかをチェックするには、文字列のスライシングではなく ''.startswith() と ''.endswith() を使う

良い例: if foo.startswith('bar'):
悪い例: if foo[:3] == 'bar':

・オブジェクトの型の比較は、型を直接比較するかわりに、常に isinstance() を使う

良い例: if isinstance(obj, int):
悪い例: if type(obj) is type(1):

・シーケンスについては、空のシーケンスが False であることを利用する

良い例: if not seq:
       if seq:

悪い例: if len(seq):
       if not len(seq):

・行末の空白文字に依存した文字列リテラルを書かない
・ブール型の値と True や False を比較するのに == を使うのはやめる

良い例:      if greeting:
悪い例:      if greeting == True:
もっと悪い例:  if greeting is True:

関数アノテーション

関数アノテーションを PEP484(https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code) とは違うスタイルで使いたいコードについては,

type: ignore

をファイルの先頭あたりに書いておく.
こうすることで、型チェックのプログラムにすべてのアノテーションを無視するように伝える.

おわりに

そういう風に書くものなんだなと理解するだけならこの程度の内容で良いと思います.
詳しく(なぜそのように書くべきなのか)知りたい方はドキュメントを参照してください.