このプロジェクトはGoogle公式プロジェクトではなく、国内のプログラマーが情熱によって作成・維持しています。
Google公式英語版を利用したい場合は、こちらへ移動してくださいGoogle Style Guide
以下のコードにおいてYesは推奨を表し、Noは非推奨を表します。
セミコロン
行末にセミコロンを付けないでください。また、セミコロンを使って2つのコマンドを同じ行に置かないでください。
行の長さ
各行は80文字を超えないこと
以下の場合は例外です:
- 長いインポートモジュール文
- コメント内のURL
バックスラッシュで行を接続しないでください。
Pythonは丸括弧、角括弧、波括弧内の行を暗黙的に接続します、この特性を利用できます。必要に応じて、式の外側に追加の丸括弧を一組加えることができます。
推荐: foo_bar(self, width, height, color='black', design=None, x='foo',
emphasis=None, highlight=0)
if (width == 0 and height == 0 and
color == 'red' and emphasis == 'strong'):
テキスト文字列が1行に収まらない場合は、丸括弧を使用して暗黙的な行接続を実現できます:
x = ('这是一个非常长非常长非常长非常长 '
'非常长非常长非常长非常长非常长非常长的字符串')
コメント内では、必要であれば長いURLを1行に置いてください。
Yes: # See details at
# http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html
No: # See details at
# http://www.example.com/us/developer/documentation/api/content/\
# v2.0/csv_file_name_extension_full_specification.html
上記の例の要素のインデントに注意してください。この文書の :ref:`インデント <indentation>` セクションで説明を見つけることができます。
括弧
括弧は必要最小限に使用する
行の接続を実現するためでない限り、return文や条件文で括弧を使用しないでください。ただし、タプルの両側に括弧を使用することは問題ありません。
Yes: if foo:
bar()
while x:
x = bar()
if x and y:
bar()
if not x:
bar()
return foo
for (x, y) in dict.items(): ...
No: if (x):
bar()
if not(x):
bar()
return (foo)
インデント
コードのインデントにはスペース4つを使用します
タブは絶対に使わず、タブとスペースを混用しないでください。行接続の場合、折り返した要素を垂直に揃えるか(:ref:`行の長さ <line_length>` セクションの例を参照)、またはスペース4つのハンギングインデントを使用してください(この場合、最初の行にパラメータを置くべきではありません):
Yes: # 与起始变量对齐
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 字典中与起始值对齐
foo = {
long_dictionary_key: value1 +
value2,
...
}
# 4 个空格缩进,第一行不需要
foo = long_function_name(
var_one, var_two, var_three,
var_four)
# 字典中 4 个空格缩进
foo = {
long_dictionary_key:
long_dictionary_value,
...
}
No: # 第一行有空格是禁止的
foo = long_function_name(var_one, var_two,
var_three, var_four)
# 2 个空格是禁止的
foo = long_function_name(
var_one, var_two, var_three,
var_four)
# 字典中没有处理缩进
foo = {
long_dictionary_key:
long_dictionary_value,
...
}
空行
トップレベル定義の間は2行空け、メソッド定義の間は1行空けます
トップレベル定義(関数やクラス定義など)の間は2行空けます。メソッド定義、クラス定義と最初のメソッドの間は1行空けるべきです。関数やメソッド内では、適切と思われる場所に1行空けます。
スペース
標準の組版規則に従って、句読点の両側にスペースを使用します
括弧内にはスペースを入れないでください。
標準の組版規則に従って、句読点の両側にスペースを使用します
Yes: spam(ham[1], {eggs: 2}, [])
No: spam( ham[ 1 ], { eggs: 2 }, [ ] )カンマ、セミコロン、コロンの前にはスペースを入れず、後ろにはスペースを入れるべきです(行末を除く)。
Yes: if x == 4:
print x, y
x, y = y, x
No: if x == 4 :
print x , y
x , y = y , x
パラメータリスト、インデックス、スライスの左括弧の前にはスペースを入れないでください。
Yes: spam(1)
no: spam (1)
Yes: dict['key'] = list[index]
No: dict ['key'] = list [index]
二項演算子の両側にはスペースを1つ入れます。例えば、代入(=)、比較(==, <, >, !=, <>, <=, >=, in, not in, is, is not)、ブール演算(and, or, not)などです。算術演算子の両側のスペースの使い方については、自分で適切に判断する必要があります。ただし、両側で一貫性を保つようにしてください。
Yes: x == 1
No: x<1
'=' がキーワード引数やデフォルト引数を示すために使われる場合、その両側にスペースを使わないでください。
Yes: def complex(real, imag=0.0): return magic(r=real, i=imag)
No: def complex(real, imag = 0.0): return magic(r = real, i = imag)
複数行にわたるトークンをスペースで垂直に揃えないでください。これは保守の負担になるためです(:, #, = などに適用):
Yes:
foo = 1000 # 注释
long_name = 2 # 注释不需要对齐
dictionary = {
"foo": 1,
"long_name": 2,
}
No:
foo = 1000 # 注释
long_name = 2 # 注释不需要对齐
dictionary = {
"foo" : 1,
"long_name": 2,
}
Shebang
ほとんどの.pyファイルは、ファイルの先頭に#!を置く必要はありません。によるとPEP-394、プログラムのmainファイルは #!/usr/bin/python2 または #!/usr/bin/python3 で始めるべきです。
(翻訳者注:コンピュータサイエンスにおいて、Shebang(またHashbangとも呼ばれます)は、井桁(#)と感嘆符(!)で構成される文字列行(#!)で、テキストファイルの最初の行の先頭2文字に現れます。ファイルにShebangが存在する場合、Unix系オペレーティングシステムのプログラムローダーはShebangの後の内容を解析し、それらの内容をインタープリタの指示として扱い、その指示を呼び出し、Shebangを含むファイルのパスをそのインタープリタの引数として渡します。例えば、#!/bin/sh で始まるファイルは、実行時に実際に /bin/sh プログラムを呼び出します。)
#! はカーネルがPythonインタープリタを見つけるのに役立ちますが、モジュールをインポートするときは無視されます。したがって、直接実行されるファイルにのみ #! を追加する必要があります。
コメント
モジュール、関数、メソッド、インラインコメントに正しいスタイルを使用するようにしてください。
ドキュメント文字列
Pythonには独自のコメント方法があります:ドキュメント文字列を使用します。ドキュメント文字列は、パッケージ、モジュール、クラス、関数内の最初の文です。これらの文字列は、オブジェクトの __doc__ メンバーによって自動的に抽出され、pydocによって使用されます。(自分のモジュールで pydoc を実行して、どのように見えるか試すことができます)。私たちのドキュメント文字列の慣例は、三重引用符 """( を使用することです。PEP-257)。ドキュメント文字列は次のように構成する必要があります:まず、句点、疑問符、感嘆符で終わる概要の1行(またはドキュメント文字列が単に1行だけの場合)。次に空行。次にドキュメント文字列の残りの部分で、ドキュメント文字列の最初の行の最初の引用符と揃える必要があります。以下に、ドキュメント文字列の書式設定に関する詳細な規約があります。
モジュール
各ファイルにはライセンスのテンプレート(雛形)を含める必要があります。プロジェクトで使用しているライセンス(例:Apache 2.0、BSD、LGPL、GPL)に応じて、適切なテンプレートを選択してください。
関数とメソッド
以下で言及する関数には、関数、メソッド、ジェネレータが含まれます。
関数にはドキュメント文字列が必要ですが、次の条件を満たす場合は除きます:
- 外部から見えない
- 非常に短い
- 単純で明確
ドキュメント文字列には、関数が何をするか、および入力と出力の詳細な説明を含めるべきです。通常、「どのように行うか」は、複雑なアルゴリズムでない限り説明すべきではありません。ドキュメント文字列は、他の人がその関数を呼び出すコードを書くときに、コードを1行も見る必要がなく、ドキュメント文字列を見るだけで済むような十分な情報を提供する必要があります。複雑なコードについては、ドキュメント文字列を使うよりも、コードの横にコメントを追加する方が有意義です。
関数に関するいくつかの側面は、特定のセクションで説明・記録する必要があります。その側面は以下のとおりです。各セクションは見出し行で始める必要があります。見出し行はコロンで終わります。見出し行を除いて、セクションの他の内容はスペース2つでインデントする必要があります。
- Args:
- 各パラメータの名前を列挙し、名前の後にコロンとスペースを1つ使用して、そのパラメータの説明を区切ります。説明が長すぎて1行の80文字を超える場合は、スペース2つまたは4つのハンギングインデントを使用します(ファイルの他の部分と一貫性を保ちます)。説明には、必要な型と意味を含めるべきです。関数が *foo(可変長引数リスト)または **bar(任意のキーワード引数)を受け取る場合は、*foo と **bar を詳細に列挙する必要があります。
- Returns:(またはジェネレータには Yields:)
- 戻り値の型と意味を説明します。関数がNoneを返す場合は、この部分は省略できます。
- Raises:
- インターフェースに関連するすべての例外を列挙します。
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ pass
类
クラスは、その定義の下にクラスを説明するドキュメント文字列を持つべきです。クラスにパブリック属性(Attributes)がある場合は、ドキュメントに属性(Attributes)セクションを設けるべきです。そして、関数パラメータと同じ書式に従う必要があります。
class SampleClass(object): """Summary of class here. Longer class information.... Longer class information.... Attributes: likes_spam: A boolean indicating if we like SPAM or not. eggs: An integer count of the eggs we have laid. """ def __init__(self, likes_spam=False): """Inits SampleClass with blah.""" self.likes_spam = likes_spam self.eggs = 0 def public_method(self): """Performs operation blah."""
ブロックコメントと行コメント
コメントを書く必要があるのは、コードの中でも技巧的な部分です。もしあなたが次回コードレビューのときに説明しなければならないなら、今すぐその部分にコメントを書くべきです。複雑な操作については、操作の開始前に数行のコメントを書くべきです。一目見ただけでは分からないコードには、行末にコメントを追加すべきです。
# We use a weighted dictionary search to find out where i is in # the array. We extrapolate position based on the largest num # in the array and the array size and then do binary search to # get the exact number. if i & (i-1) == 0: # true iff i is a power of 2可読性を高めるために、コメントはコードから少なくとも2スペース離すべきです。
一方で、コードを説明することを絶対にしないでください。コードを読む人はあなたよりもPythonに詳しいと仮定してください。彼は単にあなたのコードが何をするのかを知らないだけです。
# BAD COMMENT: Now go through the b array and make sure whenever i occurs # the next element is i+1
类
クラスが他のクラスを継承しない場合は、明示的にobjectから継承してください。ネストしたクラスも同様です。
Yes: class SampleClass(object):
pass
class OuterClass(object):
class InnerClass(object):
pass
class ChildClass(ParentClass):
"""Explicitly inherits from another class already."""
No: class SampleClass:
pass
class OuterClass:
class InnerClass:
pass
継承することobjectは、属性(properties)を正しく機能させるためです。また、これにより、Python 3000の特定の潜在的な非互換性の影響からコードを保護できます。そうすることで、オブジェクトのデフォルトのセマンティクスを実装するいくつかの特別なメソッドも定義されます。含まれるのは__new__, __init__, __delattr__, __getattribute__, __setattr__, __hash__, __repr__, and __str__ .
文字列
Yes: x = a + b
x = '%s, %s!' % (imperative, expletive)
x = '{}, {}!'.format(imperative, expletive)
x = 'name: %s; score: %d' % (name, n)
x = 'name: {}; score: {}'.format(name, n)
No: x = '%s%s' % (a, b) # use + in this case
x = '{}{}'.format(a, b) # use + in this case
x = imperative + ', ' + expletive + '!'
x = 'name: ' + name + '; score: ' + str(n)
ループ内で + や += 演算子を使って文字列を連結することは避けてください。文字列は不変であるため、これを行うと不要な一時オブジェクトが作成され、線形ではなく二次方的な実行時間になります。代替案として、各サブストリングをリストに追加し、ループ終了後に.joinリストを結合します。(各サブストリングをcStringIO.StringIOバッファに書き込むこともできます。)
Yes: items = ['<table>']
for last_name, first_name in employee_list:
items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
items.append('</table>')
employee_table = ''.join(items)
No: employee_table = '<table>'
for last_name, first_name in employee_list:
employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
employee_table += '</table>'
同じファイル内では、文字列引用符の一貫性を保つこと。文字列を引用するには単一引用符'または二重引用符"のいずれかを使用し、同じファイル内でそれを使い続けること。文字列内では別の引用符を使用して、エスケープを避けることができる。PyLintはこのチェックを既に含んでいる。
Yes:
Python('Why are you hiding your eyes?')
Gollum("I'm scared of lint errors.")
Narrator('"Good!" thought a happy Python reviewer.')
No:
Python("Why are you hiding your eyes?")
Gollum('The lint. It burns. It burns us.')
Gollum("Always the great lint. Watching. Watching.")
複数行文字列には三重単一引用符'''ではなく三重二重引用符"""を使用すること。プロジェクトが文字列に単一引用符'を使用している場合にのみ、非ドキュメント文字列の複数行文字列に三重'''を使用する可能性がある。ドキュメント文字列は三重二重引用符"""を使用しなければならない。ただし、通常は暗黙の行連結の方が明確であることに注意。複数行文字列はプログラムの他の部分のインデントと一貫しないため。
Yes:
print ("This is much nicer.\n"
"Do it this way.\n")
No:
print """This is pretty ugly.
Don't do this.
"""
ファイルとsockets
ファイルとソケットは、終了時に明示的に閉じること。
ファイル以外にも、ソケットやその他のファイル類似オブジェクトを必要もなく開くと、多くの副作用がある。例えば:
- それらはファイル記述子などの限られたシステムリソースを消費する可能性がある。これらのリソースが使用後に速やかにシステムに返還されない場合、それらを処理するコードがリソースを使い果たす可能性がある。
- ファイルを保持していると、移動や削除などの他の操作が妨げられる。
- 単に論理的にファイルとソケットを閉じただけでは、それらを共有するプログラムによって意図せず読み書きされる可能性がある。それらが実際に閉じられて初めて、読み書きの試みは例外を発生させ、問題がすぐに明らかになる。
さらに、ファイルオブジェクトが破棄されるときにファイルとソケットが自動的に閉じると想像し、ファイルオブジェクトのライフサイクルとファイルの状態を結び付けようとする考えは非現実的である。理由は以下の通り:
- ランタイムが実際にファイルのデストラクタを実行することを保証する方法はない。異なるPython実装は、遅延ガベージコレクションなどの異なるメモリ管理技術を使用する。遅延ガベージコレクションは、オブジェクトのライフサイクルを任意に無期限に延長する可能性がある。
- ファイルへの予期しない参照により、ファイルの保持期間が予想以上に長くなる可能性がある(例: 例外のトレースバック、グローバル変数など)。
推奨されるのは"with"ステートメントを使用してファイルを管理すること:
with open("hello.txt") as hello_file:
for line in hello_file:
print line
"with"ステートメントをサポートしないファイル類似オブジェクトには、contextlib.closing()を使用する:
import contextlib
with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
for line in front_page:
print line
レガシーAppEngineのPython 2.5コードで"with"ステートメントを使用する場合、"from __future__ import with_statement"を追加する必要がある。
TODOコメント
一時的なコードにはTODOコメントを使用する。それは短期的な解決策である。完璧ではないが、十分に良い。
TODOコメントは、先頭に"TODO"文字列を含み、その直後に括弧で囲んだあなたの名前、メールアドレス、またはその他の識別子を続けること。次に任意のコロン。その後、何をすべきかを説明するコメント行が必ず必要である。主な目的は統一されたTODO形式を持つことで、コメントを追加した人が検索できるようにすることである(必要に応じて詳細を提供できる)。TODOコメントを書いたからといって、書いた人が自分で問題を解決する保証はない。TODOを書いたときは、あなたの名前を記入すること。
# TODO(kl@gmail.com): Use a "*" here for string repetition. # TODO(Zeke) Change this to use relations.
TODOが「将来何かをする」形式の場合、特定の日付(「2009年11月に解決」)または特定のイベント(「すべての顧客がXMLリクエストを処理できるようになったらこのコードを削除」)を必ず含めること。
インポートの形式
各インポートはそれぞれ独立した行にすること
Yes: import os
import sys
No: import os, sys
インポートは常にファイルの先頭に置き、モジュールのコメントとドキュメント文字列の後、モジュールのグローバル変数と定数の前に置くこと。インポートは最も一般的なものから最も一般的でないものの順にグループ化する:
- 標準ライブラリのインポート
- サードパーティライブラリのインポート
- アプリケーション固有のインポート
各グループ内では、各モジュールの完全なパッケージパスに基づいて辞書順に並べ替え、大文字小文字を無視すること。
import foo from foo import bar from foo.bar import baz from foo.bar import Quux from Foob import ar
文
通常、各文は独立した行にすること
ただし、テスト結果とテスト文が1行に収まる場合は、それらを同じ行に置くことができる。if文の場合、elseがない場合にのみこれを行うことができる。特に、絶対に次のようにしないことtry/excepttryとexceptは同じ行に置くことができないため。
Yes: if foo: bar(foo)
No:
if foo: bar(foo)
else: baz(foo)
try: bar(foo)
except ValueError: baz(foo)
try:
bar(foo)
except ValueError: baz(foo)
アクセス制御
Pythonでは、些細で重要でないアクセス関数については、追加の関数呼び出しのオーバーヘッドを避けるために、パブリック変数を直接使用すべきである。より多くの機能を追加する場合、プロパティ(property)を使用して構文の一貫性を保つことができる。
(訳注: カプセル化を重視するオブジェクト指向プログラマーはこれに反感を抱くかもしれない。なぜなら彼らは「すべてのメンバー変数はプライベートでなければならない」と教えられてきたからだ。実際、それは本当に面倒だ。Python的な哲学を受け入れるようにしてみてほしい)
一方、アクセスがより複雑な場合、または変数アクセスのオーバーヘッドが顕著な場合は、次のような関数呼び出しを使用すべきである。get_foo()とset_foo()以前のコードの動作がプロパティ(property)によるアクセスを許可していた場合、新しいアクセス関数をプロパティに結び付けないこと。そうすれば、古い方法でアクセスしようとするコードは実行できなくなり、利用者は複雑さが変化したことに気づく。
命名
module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.
避けるべき名前
- 単一文字の名前。カウンターとイテレーターを除く。
- パッケージ/モジュール名のハイフン(-)
- 二重アンダースコアで始まり終わる名前(Python予約済み、例: __init__)
命名規約
- いわゆる「内部(Internal)」は、モジュール内でのみ使用可能、またはクラス内で保護またはプライベートであることを意味する。
- 単一アンダースコア(_)で始まるモジュール変数または関数は、保護されていることを示す(import * fromでは含まれない)。
- 二重アンダースコア(__)で始まるインスタンス変数またはメソッドは、クラス内でプライベートであることを示す。
- 関連するクラスとトップレベル関数は同じモジュールに置くこと。Javaとは異なり、1つのモジュールに1つのクラスに制限する必要はない。
- クラス名には大文字で始まる単語(CapWords、すなわちPascalスタイル)を使用すること。ただしモジュール名は小文字とアンダースコアを使用すること(例: lower_with_under.py)。既存のモジュールの多くがCapWords.pyのような命名を使用しているが、モジュール名がたまたまクラス名と一致すると混乱を招くため、現在は推奨されていない。
Pythonの父グイドが推奨する規約
| Type | Public | Internal |
|---|---|---|
| Modules | lower_with_under | _lower_with_under |
| Packages | lower_with_under | |
| Classes | CapWords | _CapWords |
| Exceptions | CapWords | |
| Functions | lower_with_under() | _lower_with_under() |
| Global/Class Constants | CAPS_WITH_UNDER | _CAPS_WITH_UNDER |
| Global/Class Variables | lower_with_under | _lower_with_under |
| Instance Variables | lower_with_under | _lower_with_under (protected) or __lower_with_under (private) |
| Method Names | lower_with_under() | _lower_with_under() (protected) or __lower_with_under() (private) |
| Function/Method Parameters | lower_with_under | |
| Local Variables | lower_with_under |
Main
スクリプトとして使用するつもりのファイルでも、インポート可能であるべきである。そして、単純なインポートによってスクリプトの主機能(main functionality)が実行されてはならない。それは副作用である。主機能はmain()関数に置くべきである。
Pythonでは、pydocおよびユニットテストはモジュールがインポート可能であることを要求する。コードはメインプログラムを実行する前に常にif __name__ == '__main__'をチェックすべきである。これにより、モジュールがインポートされたときにメインプログラムが実行されない。
def main():
...
if __name__ == '__main__':
main()
すべてのトップレベルコードはモジュールのインポート時に実行される。pydocを使用するときに実行すべきでない関数呼び出し、オブジェクト作成、または操作を実行しないように注意すること。