自分の確認用です. C++のスタイルガイド の確認も自分の勉強用です.
スタイルガイド
スタイルガイドは、出版物などにおいて統一した言葉遣いを規定する手引き (出典:スタイルガイド - Wikipedia)
コーディングにおいても, 基本的な書き方のルールをある程度定めることで理解しやすいコードになりうる. いくつか種類が存在する.
PEP-8
Google Python Style Guide
django
Coding style | Django documentation | Django
既存のコードに対するpep8の確認
pep8
hogehoge.py
をコマンドライン上で確認するには,
$pip install pep8 $pep8 --show-source hogehoge.py
などとする.
flake8
flake8を用いても同様に確認できる.
pip install flake8 flake8 hogehoge.py
参考:vscodeでの使用(python - Using Flake8 in VSCode...? - Stack Overflow)
autopep8
autopep8を用いることで, タブをインデントに置換するなど簡単な規約違反は自動で取り除くことができる.
pip install autopep8 autopep8 -i url.py
docstringのフォーマット
関数やクラスを説明するコメント文を docstringと呼び, これについてもいくつかの流儀がある.
代表的なものは PEP257, numpy, google のフォーマット.
- PEP257例:[Python入門]docstringの書き方:Python入門 - @IT
- numpy例:Example NumPy Style Python Docstrings — napoleon 0.7 documentation
- google例:Example Google Style Python Docstrings — napoleon 0.7 documentation
pandasなどはnumpyフォーマットを採用している. docstringを記述すれば sphinx 等からドキュメントを簡単に出力することができる. vscodeやatomにはdocstringのテンプレートを書きこむプラグインが存在するので, プロジェクトのルールに合わせてプラグインを使用する.
参考1:sphinx.ext.napoleon -- NumPy および Google スタイルの docstring をドキュメントに取り込む — Sphinx 3.0.0+/39c2131b ドキュメント
参考2:vscodeプラグイン例
autoDocstring - Visual Studio Marketplace
各スタイルガイド要約
読みながらの留め書きです, 詳しくは公式のドキュメントを参照してください.
スタイルガイドよりもプロジェクトやチーム内部でのルールが優先されます(コードを読む人たちが慣れ親しんだ規則で書くのが最も読みやすい).
PEP8
GitHub - mumumu/pep8-ja: PEP8 日本語版
- インデント
- インデントはタブかスペースで統一, スペース4回が良い
- 関数呼び出しの途中で改行する場合は
(
の位置にインデントをそろえる - 引数の一つ目から改行を入れるならばそろえなくても良い
- +/- などの二項演算子が長い場合は演算子の手前に改行を入れて演算子の位置を統一する
- リストの閉じ括弧のインデント方法は2種類
- 条件分岐
- if文の条件内部では
(
の位置からさらにインデントを入れても良い len(list)==0
ではなく空の場合はFalse
になることを利用するx == True
など真偽値を比較しない- オブジェクトの型比較は
isinstance(insA, insB)
を用いる
- if文の条件内部では
- 文字・空行・空白
- コードは一行あたり最大79文字
- コメントは一行あたり最大72文字
- クラスと関数定義の始まり手前には2行空白を入れる
- クラス内の関数定義の手前には1行空白を入れる
- 関数に複数のまとまりが存在するならば2行以上空白を入れてもいいが, 多用しない
,
,:
,;
の直後には空白が来るが, スライスの指定時には空白を入れなくても良い (list[:10]
など)- 二項演算子は演算子の両側に一つだけスペースが入る
- 代入演算子(
=
)の場合はインデントをそろえない - デフォルトパラメータを指定する(
=
)の場合はスペースを入れない (def foo(param=0)
など ) - 関数アノテーション(
->
)の前後にはスペースを入れる
- 変数名
- モジュール名:すべて小文字
- パッケージ名:すべて小文字
- クラス名:CapWords
- 関数名:mixedCase / すべて小文字
- 例外名:CapWords
- 定数:すべて大文字
- 関数引数:インスタンスメソッドは
self
, クラスメソッドはcls
をはじめに呼ぶ - 他、変数名が重複する場合はアンダースコアのルールを適用する
l
,o
,I
は見間違うので変数としては使用しない
- アンダースコア(命名規則の項目参照:PEP 8 -- Style Guide for Python Code | Python.org)
- 変数前にアンダースコア:クラス・モジュール内部でのみ使用する変数
- モジュール内のグローバル変数には付与する必要あり
from XXX import *
とした時に読み込まれないようになるが,import XXX
では呼ばれる
- 変数後にアンダースコア:キーワードと衝突しうる変数名の場合に付ける
- 変数前にアンダースコア2つ:マングリング(内部的には変数名を変更)を行う. クラス間でメソッド名重複が発生した場合に使用.
- 変数前にアンダースコア2つ, 変数後にアンダースコア2つ:通常は追加で定義しない
- アンダースコア2つは dunders と呼ぶこともある(例:What Are DUNDERS in Python? - Pranati Shete - Medium)
- 変数前にアンダースコア:クラス・モジュール内部でのみ使用する変数
- コメント
#
を用いたコメントのインデントはコメントを付けるコードのインデントに合わせる- インラインのコメント(コードと同じ行にするコメント)ではコードとの間に2つ以上のスペースを置く
- docstringフォーマットはプロジェクト・チーム内で統一する
- import
- 一つの行で異なるモジュールをimportしない (
import numpy, scipy
など) - 同じパッケージから複数のモジュールをインポートする場合は
,
で複数importして良い - import にワイルドカードは使用しない
- 一つの行で異なるモジュールをimportしない (
- その他
- エンコードは utf-8
- 文字列にて,
"
と ``` は統一されているならばどちらを用いても良い - 拡張比較メソッドは全て定義する
- pychecker
- pycheckerを用いてバグを見つける
- PyChecker: a python source code checking tool
- import
- 相対パスでのインポートはしない, 同じパッケージが複数回インポートされることを防ぐ
- モジュール名が長すぎる場合は
as
を用いて短くする
- exception
- Pythonのビルトインのクラスである Exception を継承して独自の例外を定義する
- 最も上位のブロック以外では
except:
を使わずに定義した例外を使用する try~exception~
内部のコードは可能な限り短くする- 必要ならば
finally
を用いてtry
内部での処理のクリーンアップを行う
- リスト
- リストの内包表現は簡単なもののみ利用し, 複雑な場合はループ式で記述する
- ライセンス
- 著作権表記は必ず記述する
- ファイルの原作者名を記述する
- ライセンス文をライセンスに応じて記述する
- 変数名
- クラス、例外:CapWords
- グローバル定数・クラス内定数:アンダースコア区切りの大文字
- グローバル変数・クラス内変数:アンダースコア区切りの小文字
- その他:アンダースコア区切りの小文字
- その他
- λ式はワンライナーの場合のみ使用する
- イテレータ内部ではコンテナを変更しない
- 標準のイテレータが存在するならば, それを利用する
- stringモジュールを使用することを避け, stringメソッドを使用する
- メタクラス, オブジェクトの親の変更など Python の一部の機能は使用を避ける
- バックスラッシュによる改行は使用しない
- TODOコメントのフォーマットはそろえる, 何日までに修正するなどは指定があるならば明記する
C++
C++も自学用に.
参考文献
- [1] Georg Brandl, peps: 65c5d45eab5f pep-0008.txt, 2016
- [2] Google Python Style Guide, styleguide/pyguide.md at gh-pages · google/styleguide · GitHub
- [3] sphinx.ext.napoleon -- NumPy および Google スタイルの docstring をドキュメントに取り込む — Sphinx 3.0.0+/39c2131b ドキュメント