Pythonコーディングのベストプラクティス「PEP 8」を解説：命名規則、インデント、コメントの付け方など

TechTargetは、「開発チームのPythonコーディング標準」に関する記事を公開した。Pythonを使う開発チームのリーダーには、コード標準に関して2つの課題がある。スタイルガイドを作成することと、開発者にそれを守らせることだ。

[Amy Reichert，TechTarget]

　TechTargetは2023年12月28日（米国時間）、「開発チームのPythonコーディング標準」に関する記事を公開した。

開発チームのPythonコーディング標準を設定する方法（提供：TechTarget）

　Pythonは構文的ルールと意味的ルールが混在しているため、強力なコンピューティング言語となっている。ただし、コンピュータに特定のタスクを実行させるコードの記述方法は無数にある。コーディング標準を用いることで、Pythonプログラムは可能な限り効率的かつ効果的なものになる。

　コーディング標準は、開発者のアプローチを標準化するのに役立つ。目標とするのは「他の人間やコンピュータが読みやすく、保守しやすく、アクセスできるコード」だ。開発チームには通常、複数のプログラマーがいる。コードの可読性を確保することで、全ての開発者が期待通りの方法でコードを使用できるようにする。コーディングを標準化することで、開発者間のコミュニケーションが強化され、コードベースのスケーラビリティと保守性のメリットが得られる。

　「PEP 8」は、新しいプログラマーや、この言語に精通しているプログラマーのために、Python固有のコーディング標準を提供する。

　まずはPEP 8の命名規則、インデント、コメントのガイドラインを学ぶことから始めるのがいいだろう。次に、引用符、スペース、タブ、文字、その他の書式選択の一貫性を保つためのヒントを使用して、Pythonコードをさらに改善する。そして最後に、開発チーム全体がコード標準に取り組むようにする方法を計画する。

PEP 8とは何か

　PEPは「Python Enhancement Proposal」の略で、Pythonコーディングガイドラインとベストプラクティスに関するスタイルガイドドキュメントとなっている。

　「PEP 0」は2001年にグイド・ヴァンロッサム氏、バリー・ワルシャワ氏、アリッサ・コグラン氏によって作成された。PEPの番号はPEPの編集者によって割り当てられ、現在のバージョン8に至るまで、その時点で推奨されるPythonスタイルと設計標準を備えた新しいPEPが登場してきた。

　PEP 8の目的は、コードの一貫性、品質、可読性を確保することだ。PEP 8は、コード構造と設計の一貫性を構築する。一貫性は、プロジェクト全体の問題であると同時に、単一のコードモジュールや関数の問題でもある。コードの一貫性が高ければ高いほど、他のユーザーにとって読みやすくなる。言い換えればコードベースが読みやすいほど、他の開発者が保守しやすくなるというわけだ。

基本的なPythonフォーマット標準

　PEP 8は、Python内の幾つかの一般的な標準を示している。もちろん基準には例外もあるので、必要に応じて創造性を発揮しなければならない。Pythonコーディングのベストプラクティスに従うには、命名規則、インデント、コメントに焦点を当てる。

命名規則

　Pythonの命名規則のライブラリは、開発者が名前を割り当てるコードアーキテクチャのパーツとピースに適用される。新しいモジュールとパッケージ名は、一貫性と可読性を持たせるために、全て以下の基準に従って記述する。

• 全ての名前に対して「優先原則」に従うこと。「コードがどのような機能を果たすか」ではなく「用途」に基づいて名前を作成する。また、分かりやすい名前を使うこと
• Pythonの一般的な命名規則オプションには、次のものがある

• 小文字か大文字を1文字使うケース。例えば「p」「P」など
• 全て小文字にするケース。例えば、クラスファイルを「classfile」と記述する
• スネークケース。単語をアンダーバーで蛇のようにつなげる。例えば「class_file_open」など
• 全て大文字にするケース。例えば、クラスファイルを「CLASSFILE」と記述する
• スネークケースの大文字バージョン。例えば「CLASS_FILE_OPEN」など
• CapWordsまたはCamelCase。各単語の最初の文字を大文字にする
• MixedCase。小文字で始まり、次の単語は大文字にする。例えば「classFileOpen」など
• CamelCaseとスネークケースの組み合わせ。例えば「Class_File_Open」など

• 命名規則では、フォーマットの一貫性を保つためにアンダースコアも使用できる。一般的なアプローチは以下の通り

• 単一の末尾アンダースコアを付けるアプローチ。例えば「single trailing underscore_」
• 先頭の二重アンダースコアを付けるアプローチ。例えば「__boo move」
• 先頭と末尾に二重アンダースコアを付けるアプローチ。例えば「__boo move__」

• 1と0に似ている名前は避ける。間違えやすい表記は以下の通り

• 小文字のエル（l）
• 大文字のアイ（I。例えば“Ignore”など）
• 大文字のオー（O。例えば“Oh”など）

• 標準ライブラリで使用される全ての識別子は、ASCII互換でなければならない
• パッケージ名とモジュール名に関するPythonのガイダンスは、小文字の短い名前に焦点を当てており、読みやすくするために必要に応じて他の文字に依存している。こうした名前にアンダースコアは使用しない方がよい
• クラス名にはCamelCase形式を使う。そのクラスの主な用途が呼び出し可能なインタフェースである場合は、関数と同様に、アンダースコアで区切られた小文字を使用する
• 変数名の場合、ベストプラクティスに従うとCamelCase形式で短い名前を指定する必要がある。例えば「_co」（Add _co to declare covariant behavior）、「_contra」（Add _contra to declare contravariant behavior）など
• グローバル変数は、単一のモジュール内でのみ使用する。前後に二重アンダースコアが付いた「__xxx__」といった形式はグローバル変数を示す
• 読みやすさが向上する場合、関数名は小文字とスネークケースを使うが、後方互換性を維持するために必要に応じてMixedCase形式で表示する
• モジュールレベルの定数は、全て大文字にし、単語をアンダーバーでつなぐスネークケースで名前を付ける
• 命名規則は、インタフェースがパブリックか内部かを示すことができる。非公開または非公開APIを示すには「__all__」を使用する
• Pythonで名前を付けるときは継承を考慮して設計しなければならない。詳細は以下の通り

• 先頭にアンダースコアは使わない
• パブリック名が予約済みキーワードと競合する場合は、名前の末尾にアンダースコアを1つ追加する
• パブリックデータ属性の場合は、属性の名前のみを指定する
• クラスをサブクラス化する必要がある場合は、サブクラス化しない属性の名前の先頭に2つのアンダースコアを付ける

インデント

　Pythonは、インデントレベルごとに4つのスペースを使う。行を継続している場合は、吊り下げインデントを使用して括弧、中括弧、大括弧内で結合するPythonの行を使って垂直方向に折り返す。吊り下げインデントでは、最初の行で引数を使用せず、継続行を区別するために2番目のインデントを使う。

# Correct:
# 開始区切り文字に合わせる
foo = long_function_name(var_one, var_two,
                         var_three, var_four)
# 引数を区別するために、スペースを4つ（インデントを1つ）追加する
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)

　if文の条件付き部分が複数行を占める場合は、2文字のキーワードとスペースを使用し、開き括弧を追加して4スペースのインデントを作成する。

#余分なインデントはない
if (this_is_one_thing and
    that_is_another_thing):
    do_something()
# コメントを追加する。これによって編集者を区別できる
# 構文の強調表示をサポートする
if (this_is_one_thing and
    that_is_another_thing):
    # Since both conditions are true, we can frobnicate.
    do_something()
# 条件付き継続行にインデントを追加する
if (this_is_one_thing
        and that_is_another_thing):
    do_something()

コメント

　開発者の中にはコメントを「必要悪」と捉えている人もいるだろう。コメントは、他の人が理解できるコードベースを構築するために不可欠な要素だ。コメントは完全な文章で書く必要がある。コメントを記載したら、明確で理解しやすいものになっているかどうか見直すことが重要だ。他の開発者にコメントを解釈してもらい、彼らが自身の意図した通りコメントを理解できているかどうか確認するといいだろう。もしそれが間違っているのであればコメントを編集すべきだ。

　また、コメントは常に最新でなければならない。コードを変更する場合は、そのコードの機能と一致するようにコメントを更新する必要がある。PEP 8スタイルガイドに従うなら、コメントは英語で作成する。コメントを1つの言語に集約することで、転送可能性を確保できる。

　Pythonはコード構造に応じて複数のコメントタイプをサポートしている。コードと同じようにインデントされたブロックコメントを使用する。コメントを始めるには、「#」の後にスペースを1つ追加する。コメント内の段落は単一の「#」を使って区切る。

　インラインコメントを使うのもいいだろう。これらのコメントは、コード文と同じ行に表示される。コード文のインラインコメントは2つのスペースで区切ることができる。インラインコメントは、「#」と1つのスペースで始められる。

その他のPython標準

　Pythonのコードを書いている開発者は、PEP 8と、最新の状態を維持するためのあらゆるアップデートに目を通すべきだ。以下は人気のあるPythonコーディング標準の簡単なリストとなっている。

• 末尾のスペースは避ける
• 改行を意味するスペース付きのバックスラッシュ文字は使わないこと
• 次の二項演算子は、両側を1つのスペースで囲む：=、<、>、!=、<>、<=、>=、in、not in、is、is not、or not
• コードベース全体の文字列には、シングルクオートまたはダブルクオートを使用する。これらは混在させてはいけない。もしトリプルクオート文字列であれば、常にダブルクオートを使う
• トップレベルの関数とクラス定義を囲むには、2つの空白行を使う
• 論理セクションを分離するには、関数内で空白行を使う
• UTF-8エンコーディングを使用する
• 非ASCII文字は、場所や人名を示すために必要な場合にのみ使用する
• 英語のASCII識別子のみを使う
• スペースはインデントに使い、タブには使用されない。混在させないようにしなければならない。
• 一行は最大79文字に制限する

チームはコーディング標準をどのように適用すべきか

　標準化は難しいテーマであり、デリケートな作業となる。とはいえ、コードの読みやすさと一貫性はPython言語の基礎であり、それを達成するためには開発者は標準に忠実でなければならない。

　コーディング標準を実装、強制する開発チームは、多くの場合、個々のスタイルや好みに合わせて作業する開発チームよりも生産性が高くなる。コーディングに必要以上に手間をかける必要はないのだ。標準に基づく一貫性のある読みやすいコードによって、全員の時間とフラストレーションが軽減される。さらに、個別的で非標準的なコーディング手法によって発生するトラブルやその解決に時間をかけなくてもよくなる。

　開発チームは、組織とチームに適したPythonコーディング標準を確立しなければならない。チームリーダーはまず、コーディング標準のテーマに関するディスカッションまたは一連のディスカッションから始める必要がある。チームメンバーがどの部分に納得していないかを調べ、時間をかけて、Python標準を基にしたチームコーディング標準を作成する。開発者は、透明性のある決定に従い、提案を考慮に入れる可能性が高くなる。

　コードレビューやその他のディスカッションの際には、矛盾や標準への「順守の甘さ」に耳を傾ける必要がある。開発者が標準に従わず、チームの生産性と結束力が損なわれていることが分かった場合は、すぐに1対1のディスカッションを開催すべきだ。アクションを起こす前に、コードの品質が損なわれないようにするためだ。また、「合意」と「透明性」を確保するために、Pythonのコーディング標準とスタイルガイドの更新の全てにチームを参加させるべきだ。

　ただ、場合によって「PEP 8を破る」という選択をすることもある。シナリオによっては、スタイルガイドや標準がコードベースを助けるどころか、複雑化してしまうこともある。こうした場合を考慮し、PEP 8は、開発者がコードを読みにくくしたり、古いコードモジュールを壊したり、コードが下位互換性を持つのを防ぐときに、Python標準に反することを奨励している。