Python のコーディング規約 PEP8 (後編)

　今回の記事では、前回に引き続き、pythonにおけるコーディング規約として有名な "PEP8"について紹介していきたいと思います！
　前回紹介したコーディング規約については以下の通りです！

コードレイアウト
- インデント
- タブ or スペース
- 1行の長さ
- 2項演算子は改行前？改行後？
- 空行
- エンコーディング
- import
- モジュールレベルのアンダーネーム
文字列のクォーテーション
空白の扱い

Python のコーディング規約 PEP8 (前編)
　みなさんは、コーディングをしているときにコーディング規約を意識して書いていたりしますか？動くだけではなく、他の人や未来の自分に向けて読みやすいコードを書くためには守ることは大事ですよね！今回の記事では、pythonにおけるコーディング規...
ai-research-collection.com
2021.11.07

今回の記事では、この続きを紹介していきたいと思います！！

末尾にカンマをつけるべき場合

　末尾に,(カンマ)をつけるか否かは基本的には任意であるが、要素が1つだけのタプルを作る際は例外的に必要！

# 非推奨
FILES = 'README.md',

# 推奨
FILES = ('README.md',)

また、複数行にわたる場合もカンマで改行して記述することが推奨されている。

#非推奨
FILES = [file1, file2, file3,]

#推奨
FILES = [file1,
         file2,
         file3,
         ]

　コメントを書く上での基本原則としてあげられるのが、「コードと矛盾したコメントは、コメントがないよりも最悪だ」ということ。以下のようなことを守ることが重要です！

コードが変更された場合は、コメントを更新して、常に最新状態に！(コードだけ更新してコメントが前バージョンのまま放おっておかない！)
コメントは完全な文章になるように
最初の文字は大文字
ブロックコメント : 完全な文での 1段落以上 + ピリオドで終わる
複数の文で構成されるコメント : 最後の文の後を除き、文末のピリオドの後に2つのスペースを使用する
基本は英語で書く (記述している言語圏の人以外に120%読まれないと確信できない限りは)

① ブロックコメント

# のみを使った 1行で書く
コードと同じレベルでのインデント

② インラインコード

行末に書くコメントアウト

使用はなるべく控える
文とコメントの間には、2つのスペース
# の後はスペース 1つ

DocString

　DocString は、Document String の略。コード中に記述することでドキュメンテーションを作れるようにするものであるが、この詳しい記述形式については、PEP257にてまとめられている。

すべてのpublicのモジュールや関数、クラス、メソッドを書く
複数行 : 最後の “””　は、単独で書く
1行で書く場合 : “”” <内容> “””

命名規則

① 一番重要な原則

　APIなどとして公開する場合は、使用者が理解しやすいように、使い方を反映した名前にするべき

② 実践されている命名規則

　よく知られているものとしては以下の通り

a (小文字1文字)
A (大文字1文字)
lowercase (すべて小文字)
lower_case_withunderscores (すべて小文字 or : スネークケース)
UPPERCASE (すべて大文字)
UPPER_CASE_WITHUNDERSCORES (すべて大文字 or )
CapitalizedWords (CapWords)
camelCase (キャメルケース : はじめが小文字のところだけCapWordsと異なる)

　また、アンダースコアを名前の前後に付ける特別なやり方が知られている(これらに大文字小文字に関する規約を組み合わせるのが一般的)
(1) _single_leading_underscore (前に 1つのアンダースコア)
　「内部だけでのみ使う」 from M import * では import されない
(2) single_trailing_underscore_ (後ろに 1つのアンダースコア)
　 python のキーワードと衝突を避けるために使われる
(3) __double_leading_underscore (前に 2つのアンダースコア)
　クラスの属性に名前をつけるときに、名前のmanglingを呼び出す
(4) __double_leading_and_trailing_underscore__ (前後に2つのアンダースコア)
magic オブジェクトや属性。ドキュメントに書かれているものだけを使用する

③ 守るべき命名規則

(1) 避けるべき文字　Names to Avoid

　‘l’ (小文字のエル)、'O' (大文字のオー)、'I'(大文字のアイ)

(2) ASCIIとの互換性　ASCII Compatibility

　標準ライブラリで使われる識別子は、PEP 3131 の policy section にあるとおり、 ASCII と互換性がなければいけない

(3) パッケージとモジュールの名前　Package and Module Names

すべて小文字で短い名前にまとめる！
モジュール名では _ を使っても良いが、パッケージ名では非推奨

(4) クラス名　Class Names

　CapWords 方式 : 最初の1文字を大文字、それ以降はキャメルケース

(5) 型変数の名前 Type Variable Names

　PEP 484 で導入された型変数の名前には、通常 CapWords 方式を使う
また、 T や AnyStr や Num のような短い名前が好ましい。
(covariant や contravariant な振る舞いをする場合 : _co や _contra のような名前を変数の末尾に付け加えることを推奨)