Python PEP:8 コーディングスタイルガイドとPEP:257 Docstringガイド
Publish date: 2021-02-18
有名なPythonコードのコーディング規約である PEP 8と Docstringの規約PEP 257 の簡単な解説です。
ドキュメンテーション文字列
PEPとは
PEPとは Python Enhancement Proposal(Python拡張提案)の事です。
Pythonコミュニティへの情報提供や、新機能や環境の説明のためにまとめられた文書です。
PEP8、PEP 257とは
PEPは多数あります。 その中でもタイトル「Style Guide for Python Code」というものが、 Pythonコードのコーディング規約であるPEP8です。 PEP257のタイトルは「Docstring Conventions」です。
PEP8 Style Guide for Python Code の一部抜粋
PEP8の内容から一部を抜粋し、以下に記載します。
インデント
インデントはスペース4つにする。タブやスペース2,6,8等にはしない。
括弧やブラケットの位置をそろえる。
# 開き括弧に揃える
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 引数とそれ以外を区別するため、スペースを4つ(インデントをさらに)加える
def long_function_name(
var_one, var_two, var_three,
var_four):
print(var_one)
# 突き出しインデントはインデントのレベルを深くする
foo = long_function_name(
var_one, var_two,
var_three, var_four)
my_list = [
1, 2, 3,
4, 5, 6,
]
result = some_function_that_takes_arguments(
'a', 'b', 'c',
'd', 'e', 'f',
)2項演算子の改行
2演算子の前で改行を行う。
# 正しい:
# 演算子とオペランドを一致させやすい
income = (gross_wages
+ taxable_interest
+ (dividends - qualified_dividends)
- ira_deduction
- student_loan_interest)空行
トップレベルの関数やクラスは、2行ずつ空けて定義する。 クラス内部では1行ずつ空けてメソッドを定義する。
import
import文は次の順番でグループ化して、それぞれのグループ間に1行空白を入れる。
- 標準ライブラリ
- サードパーティに関連するもの
- ローカルな アプリケーション/ライブラリ に特有のもの
式や文中の空白文字
余計な括弧は使わない。
# 正しい:
spam(ham[1], {eggs: 2})
foo = (0,)
if x == 4: print x, y; x, y = y, x
# 間違い:
spam( ham[ 1 ], { eggs: 2 } )
bar = (0, )
if x == 4 : print x , y ; x , y = y , x命名規約
- モジュールの名前は全て小文字の短い名前にする(読みやすくなるならアンダースコアも使う)
- パッケージの名前は全て小文字の短い名前を使う
- クラスの名前はCamelCase
- 例外の名前はCamelCase、例外の名前の最後に"Error"をつける
- 関数の名前は小文字のみ、必要に応じてアンダースコアを使う
- 変数の名前は小文字のみ、必要に応じてアンダースコアを使う
- インスタンスメソッドのはじめの引数の名前は常にself
- クラスメソッドのはじめの引数の名前は常にcls
- 公開されていないメソッドやインスタンス変数にだけ、先頭にアンダースコア
- 定数はすべて大文字、アンダースコアで区切る
PEP 257 Docstring Conventions の一部抜粋
PEP257の内容から一部を抜粋し、以下に記載します。
Docstringとは
docstringとはモジュール、関数、クラス、メソッド定義の最初に登場する文字列リテラルです。
互換性のため、2重引用符3つ"""で記載する。
1行のDocstring
端的な文章で"""で囲む。
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
...複数行のDocstring
"""で開始し、"""のみの行で終了する。
先頭1行目は1行のDocstringと同様で、空行を入れてから詳細の説明を記載する。
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0:
return complex_zeroDocstringの利用
Pythonドキュメンテーション文字列(Docstring)は、エディタ等各種ツールから参照する事ができます。
コード上は__doc__でアクセス可能です。
complex.__doc__
## => 'Form a complex number.\n\n Keyword arguments:\n real -- the real part (default 0.0)\n imag -- the imaginary part (default 0.0)\n '