Pythonでのコーディングに関するGoogleのヒント。 パート2：ソースコードの書式設定のヒント

行をセミコロンで区切ったり、セミコロンを使用して同じ行にあるコマンドを区切ったりしないでください。

例外

• 長いインポート文字列
• コメント内の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 = ('This will build a very long long ' 'long long long long long long string')
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

コメントについては、必要に応じて1行に長いURLを入力します。



良い：

  # See details at # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

  # See details at # http://www.example.com/us/developer/documentation/api/content/\ # v2.0/csv_file_name_extension_full_specification.html
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

上記の行の要素のインデントに注意してください（詳細については、インデントのセクションを参照してください）。

改行を整理したくない場合は、 return式や条件付き構造でそれら（ブラケット）を使用しないでください。 （上記を参照）。 ただし、タプルの作成には括弧が適しています。



良い：

 if foo: bar() while x: x = bar() if x and y: bar() if not x: bar() return foo for (x, y) in dict.items(): ...
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 if (x): bar() if not(x): bar() return (foo)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

行の折り返しを意味する場合は、行の長さに関する例で説明されているように、折り返された各要素を垂直方向に整列させるか、4つのスペースのインデントを使用する必要があります。この場合、最初の行に単一の引数はありません。



良い：

 # Aligned with opening delimiter foo = long_function_name(var_one, var_two, var_three, var_four) # 4-space hanging indent; nothing on first line foo = long_function_name( var_one, var_two, var_three, var_four)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 # Stuff on first line forbidden foo = long_function_name(var_one, var_two, var_three, var_four) # 2-space hanging indent forbidden foo = long_function_name( var_one, var_two, var_three, var_four)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

最上位の宣言の間には2つの空行があり、メソッド宣言の間には1つの空行があるはずです。 最上位の宣言の間には、クラスであれ関数であれ、2行の空白行が必要です。 メソッドの定義の間、およびクラスの宣言とその最初のメソッドの間には、1行の空行が必要です。 関数とメソッドの内部では、必要に応じて単一の空の文字列を使用します。

角かっこ内にスペースはありません。

良い： スパム（ハム[1]、{卵：2}、[]）

悪い： スパム（ハム[1]、{卵：2}、[]）



セミコロン、セミコロン、またはピリオドの前にスペースはありません。 行末にある場合を除き、小数点、セミコロン、またはピリオドの後にスペースを使用します。



良い：

 if x == 4: print x, y x, y = y, x
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 if x == 4 : print x , y x , y = y , x
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

引数リスト、インデックス、またはスライスを開始する開始ブラケットの前にスペースはありません。

良い： スパム（1）

悪い： スパム（1）

良い： dict ['key'] =リスト[インデックス]

悪い： dict ['key'] = list [index]

両側に単一のスペースを含む二項演算子を囲み、これは割り当て（ = ）、比較演算子（ ==、<、> 、! =、<>、<=、> =、In、not in、is、is not ）に適用され、ブール演算子（and、or、not）。 適切だと思うものを使用してください

算術演算子に関してはスペースを使用しますが、バイナリ演算子の両側に常にスペースを配置すると、コードの整合性が確保されます。

良い： x == 1

悪い： x <1

名前付き引数またはデフォルト値を示すために=記号を使用する場合は、=記号の両側にスペースを使用しないでください。



良い：

 def complex(real, imag=0.0): return magic(r=real, i=imag)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 def complex(real, imag = 0.0): return magic(r = real, i = imag)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

位置合わせは面倒なので、スペースを使用して連続する行の部分を垂直に位置合わせしないでください。 （適用対象：、＃、=など）：



良い：

 foo = 1000 # comment long_name = 2 # comment that should not be aligned dictionary = { 'foo': 1, 'long_name': 2, }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

  foo = 1000 # comment long_name = 2 # comment that should not be aligned dictionary = { 'foo' : 1, 'long_name': 2, }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

＃！/ Usr / bin / pythonを使用してメインプログラムファイルを実行します。 この行は、カーネルがPythonインタープリターを見つけるために使用されますが、モジュールがインポートされるときにPythonによって無視されます。 これは、直接実行されるファイルに必要です。

モジュール、関数、メソッド、または文字列コメントに正しいスタイルを使用してください。

ドキュメント行。

Pythonには、独自のコメントスタイル（ドキュメント行）があります。 ドキュメント行は、パッケージ、モジュール、クラス、または関数の最初の構成要素である行です。 このような文字列は__doc__オブジェクト属性を使用して自動的にエクスポートでき、pydocで使用されます。 （モジュールでpydocを実行して、どのように見えるかを確認してください。）ドキュメンテーションラインアグリーメントでは、3行の二重引用符を使用して、そのような行を構成します。 ドキュメンテーション行は、空行に続く文字数、疑問符または感嘆符の数が一致するサマリー行（1つの物理行）として編成し、カーソル位置からの残りのドキュメンテーション行を最初の行の最初の引用として配置する必要があります。 以下は、ドキュメント行の設計に関するさらに詳しい情報です。

モジュール

各ファイルにはライセンステンプレートが含まれている必要があります。 プロジェクトに適したライセンステンプレートを選択します（たとえば、Apache 2.0、BSD、LGPL、GPL）。

関数とメソッド

このセクションで使用される用語（関数）は、メソッド、関数、およびジェネレーターを指します。

以下に説明する場合を除き、関数にはすべての場合にドキュメント行が必要です。

• モジュールの外側からは見えません
• とても短い
• 明らか（読みやすい）

ドキュメント行は、ソースコードを読み取らずに関数呼び出しを行うのに十分な情報を提供する必要があります。 ドキュメント行では、関数呼び出しの構文とそのセマンティクスを説明する必要がありますが、その実装については説明しないでください。 扱いにくいコードの場合、ソースコード内のコメントはドキュメント行よりも望ましいです。 関数の特定の側面は、以下にリストされている特別なセクションで文書化される必要があります。 各セクションは、ドットで終わるタイトルバーで始まります。 セクションは、ヘッダーを除き、2つのスペースでインデントする必要があります。

引数 ：

各パラメーターを名前でリストします。 説明は名前のすぐ後に続き、ドットとスペースで区切る必要があります。 説明が長すぎて80文字に収まらない場合は、2つまたは4つのスペースの中断インデントを使用します（ファイル全体のデザインに一貫性を持たせる）。

説明では、引数の必要なタイプと目的を参照する必要があります。 関数が* foo（可変長引数リスト）および/または** bar（キー値引数の任意のセット）を許可する場合、それらは* fooおよび** barとして記述される必要があります。

戻り値 ：（またはジェネレーターのイールド ）

戻り値のタイプとセマンティクスを説明します。 関数が常にNoneを返す場合、このセクションはオプションです。

発生 ：

このインターフェースで可能なすべての例外のリスト。

 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
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

クラス

クラスには、宣言の下にドキュメント行が必要です。 クラスにパブリック属性がある場合、属性セクションにすぐに文書化し、引数セクションと同じ書式スタイルに従う必要があります。

 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
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

これは、ネストされたクラスにも適用されます。



良い：

 class SampleClass(object): pass class OuterClass(object): class InnerClass(object): pass class ChildClass(ParentClass): """Explicitly inherits from another class already."""
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 class SampleClass: pass class OuterClass: class InnerClass: pass
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

プロパティを正しく機能させるには、オブジェクトクラスから継承する必要があり、Python 3000との非互換性からコードを保護します。また、オブジェクトの標準的なセマンティクスを実装する特別なメソッドを定義します。 、__ repr__、および__str__ 。

すべてのパラメータが文字列であっても、％演算子を使用して文字列をフォーマットします。 ％演算子の代わりに+演算子の使用を慎重に検討してください。



良い：

 x = a + b x = '%s, %s!' % (imperative, expletive) x = 'name: %s; score: %d' % (name, n)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 x = '%s%s' % (a, b) # use + in this case x = imperative + ', ' + expletive + '!' x = 'name: ' + name + '; score: ' + str(n)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

次のように、+および+ =演算子を使用して文字列をループに連結しないでください。 文字列は不変のデータ型です;このアプローチは不要なオブジェクトを作成し、線形法則ではなく二次法に従ってランタイムを増加させます。 代わりに、各サブストリングをリストに追加し、ループの終了後にjoinメソッドを使用します（または各サブストリングをcStringIO.StringIOバッファーに書き込みます）



良い：

 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)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 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>'
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

複数行の文字列には、「」の代わりに「」を使用します。 ただし、次のように、明示的な文字列連結を常に使用することをお勧めします。 複数行の行は、同じインデントでプログラムが終了するまで続きません。



良い：

 print ("This is much nicer.\n" "Do it this way.\n")
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 print """This is pretty ugly. Don't do this. """
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

開いているファイル、ソケット、その他のファイル型のオブジェクトを無視すると、次のような多くの副作用があります。

• ファイル記述子などの限られたシステムリソースを消費する可能性があります。 多くのオブジェクトに関連付けられているコードは、使用後にシステムに返されない場合、それらのリソースが枯渇して無駄になる可能性があります。
• ファイルを開いたままにしておくと、移動や削除などの他のアクションがファイルに引き継がれるのを防ぐことができます。
• コードを介して公開されているファイルとソケットは、論理的に「閉じられた」後に誤って読み書きされる可能性があります。

それらが実際に閉じられている場合、読み取りまたは書き込みを試みると例外がスローされるため、問題を非常に迅速に検出できます。 さらに、オブジェクトのコンストラクターが呼び出されると、ファイルとソケットは自動的に閉じられますが、オブジェクトの有効期間をファイルの状態に関連付けることは、次の理由から悪い習慣です。

• プログラムの実行中にオブジェクトのコンストラクターが呼び出される保証はありません。 さまざまな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
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

Python 2.5で書かれた古いコードは、 from __ Future__ import with_statementからのインポートでwithコンストラクトの使用を有効にすることができました 。

TODOコメントには、各コメントの先頭にTODO行を含め、その後に名前、メールアドレス、またはかっこで示された問題の解決策を提供できる最善の方法のその他の識別子を含める必要があります。 ポイントはオプションです。 そこで何が起こるべきかを説明するコメントは必要ありません。 主な目標は、TODOの一般的な形式です。これにより、問題のより詳細な説明を提供できる特定の人物をすばやく見つけることができます。 TODOは、人がこの問題を解決することを保証するものではありません。 したがって、TODOを作成すると、ほとんどの場合、名前のみが含まれます。

 # TODO(kl@gmail.com): Use a "*" here for string repetition. # TODO(Zeke) Change this to use relations. If your TODO is of the form "At a future date do something" make sure that you either include a very specific date ("Fix by November 2009") or a very specific event ("Remove this code when all clients can handle XML responses.").
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

良い：

 import os import sys
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 import os, sys
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

インポートは常に、ファイルの先頭、モジュールレベルのコメント、ドキュメント行の直後、定数を宣言する前、

モジュールレベルのオブジェクト。 インポートは、最も単純なものから最も複雑なものの順にグループ化する必要があります。

• 標準ライブラリからのインポート
• サードパーティのインポート
• アプリケーションライブラリからインポートする

グループ化に加えて、インポートは各モジュールへのフルパスに従って、大文字と小文字を区別せずに辞書式にソートする必要があります。

 import foo from foo import bar from foo.bar import baz from foo.bar import Quux from Foob import ar
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ただし、テキストの結果を条件と同じ行に配置できます。 ただし、これは式全体が1行に配置されている場合にのみ実行できます。 特に、try / exceptコンストラクトでこれを行うことはできません。 tryとexceptを同じ行に置くことはできません。また、if構文WITHOUT elseを使用して同じ行に収めることができます。

良い：

 if foo: bar(foo)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

悪い：

 if foo: bar(foo) else: baz(foo) try: bar(foo) except ValueError: baz(foo) try: bar(foo) except ValueError: baz(foo)
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ゲッター関数が単純な場合、ゲッター関数のパブリック変数を使用して回避する必要があります

Python内部呼び出しの追加リソースオーバーヘッド。 多くの機能が追加されると、プロパティを使用できます。

インターフェイスの整合性を追跡するため。 一方、ゲッター関数がより複雑である場合、または変数へのアクセス速度が非常に重要な場合は、get_foo（）やset_foo（）などの関数呼び出し（ガイドラインの次のセクションを参照）を使用する必要があります。 動作がプロパティを介したアクセスを許可する場合、新しいゲッターをプロパティにバインドしないでください。 古いメソッドを使用して変数にアクセスしようとしているコードは、アクセスの複雑さが変更されたという警告を受け取ることができるように、明示的にクラッシュする必要があります。

module_name、package_name、ClassName、method_name、ExceptionName、function_name、GLOBAL_CONSTANT_NAME、global_var_name、instance_var_name、function_parameter_name、local_var_name。



避けるべき名前：

• カウンターまたはイテレーターを除く単一文字の名前
• モジュールとパッケージの名前の短所。
• 二重アンダースコア（名前の先頭と末尾）は、言語用に予約されています。

命名規則

• 「内部」-モジュールの内部、保護クラスまたはプライベートクラスを意味します。
• 先頭のアンダースコア（_）置換は、保護されたモジュール変数および関数（インポート* fromからインポートされない）でサポートされます
• 二重の先頭のアンダースコア（__）を変数またはメソッドの名前に置き換えると、事実上、このクラスに対してプライベートになります（名前への追加を使用します）。 関連するクラスと最上位レベルをモジュールにまとめる。 Javaとは異なり、1つのモジュールで1つのクラスを作成することに制限する必要はありません。
• クラスの命名にはラクダ表記を使用し、モジュール名には大文字と下線を使用した表記を使用します。 命名にラクダ表記を使用するモジュールは多数ありますが、誤解を招く可能性があるため、そうすることはお勧めしません。 モジュールはクラスにちなんで命名されます。 （待って、インポートStringIOを書いたのですか、それともStringIOインポートStringIOからですか？）

Guidoの推奨に基づくスタイル：

種類	外部	社内
パッケージ	lower_with_under
モジュール	lower_with_under	_lower_with_under
クラス	CapWords	_CapWords
例外	CapWords
機能	lower_with_under（）	_lower_with_under（）
グローバル/クラス内定数	CAPS_WITH_UNDER	_CAPS_WITH_UNDER
グローバル/サブクラス変数	lower_with_under	_lower_with_under
クラスインスタンス変数	lower_with_under	_lower_with_under（保護）または__lower_with_under（プライベート）
メソッド名	lower_with_under（）	_lower_with_under（）（保護）または__lower_with_under（）（プライベート）
関数/メソッドの引数	lower_with_under
ローカル変数	lower_with_under

インポートするためにファイルが作成された場合でも、通常のインポートでは、スクリプトの機能部分の実行という形での副作用はありません。 主な機能はmain（）関数に配置する必要があります。

Python、pychecker、pydoc、および単体テストには、インポートされたモジュールが必要です。 コードは、実行前に__name__ == '__main__'かどうかを常に確認する必要があります。つまり、モジュールを別のプログラムにインポートするときに、モジュールが完全に実行されないことを意味します。

 def main(): ... if __name__ == '__main__': main()
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

モジュールがインポートされると、すべての最上位コードが実行されます。 関数を呼び出したり、オブジェクトを作成したり、pycheckerを使用してファイルを検証したり、pydocを使用してドキュメントを収集するときに実行すべきでない他のタイプの操作を実行しないように注意してください。

他の人のコードを編集している場合は、数分かけてこのコードを調べて、自分で書くスタイルを選択してください。 , . , (#) , . , , , .

, , . , — , . .