Commits

Toru Furukawa committed fe6ba8e

rst.

  • Participants
  • Parent commits 405ec83

Comments (0)

Files changed (1)

 PEP: 8
 Title: Style Guide for Python Code
-Version: 00f8e3bb1197
-Last-Modified: 2011-06-13 12:48:33 -0400 (Mon, 13 Jun 2011)
-Author: guido@python.org (Guido van Rossum), barry@python.org (Barry Warsaw)
+Version: $Revision$
+Last-Modified: $Date$
+Author: Guido van Rossum <guido@python.org>,
+        Barry Warsaw <barry@python.org>
 Status: Active
 Type: Process
+Content-Type: text/x-rst
 Created: 05-Jul-2001
 Post-History: 05-Jul-2001
 
 
 はじめに
+========
 
-    この文書は、主な Python ディストリビューション用の標準ライブラリを含
-    む、Pythonコーディングの慣例を提供する。Python を C で実装する場合の
-    コーディングスタイルの指針は、Style Guide for C Code [1] を参照さ
-    れたし。
+この文書は、主な Python ディストリビューション用の標準ライブラリを含む、
+Pythonコーディングの慣例を提供する。Python を C で実装する場合の
+コーディングスタイルの指針は、Style Guide for C Code [1]_ を参照されたし。
 
-    この文書は Guido の Python Style Guide[2] に、Barry のスタイルガイ
-    ド[5] の一部を追加して、改作したものである。矛盾した部分がある場合
-    は、Guido のスタイルを優先する。この PEP は未だ不完全かも知れない
-    (実際のところ、完成することはないかも知れない (^_^;)。
+この文書は Guido の Python Style Guide [2]_ に、Barry のスタイルガイド [5]_
+の一部を追加して、改作したものである。矛盾した部分がある場合は、
+Guido のスタイルを優先する。この PEP は未だ不完全かも知れない
+(実際のところ、完成することはないかも知れない (^_^;)。
 
 愚かな一貫性は小人物に憑いたおばけである
+========================================
 
-    Guido の重要な洞察のひとつは、コードは書かれる頻度よりも、読まれる頻
-    度のほうが高いということだ。ここで提供されるガイドラインは、コードの
-    可読性を高め、広範囲の Python コードに一貫させることを、意図されてい
-    る。PEP 20 [6] が述べるとおり可読性は重要である。
+Guido の重要な洞察のひとつは、コードは書かれる頻度よりも、
+読まれる頻度のほうが高いということだ。
+ここで提供されるガイドラインは、コードの可読性を高め、
+広範囲の Python コードに一貫させることを、意図されている。
+PEP 20 が述べるとおり可読性は重要である。
 
-    スタイルガイドは一貫性に関わるものであり、重要なのは規定される一貫性
-    である。プロジェクト内の一貫性は、もっと重要である。モジュールや関数
-    内部での一貫性は、更に重要である。
+スタイルガイドは一貫性に関わるものであり、重要なのは規定される一貫性である。
+プロジェクト内の一貫性は、もっと重要である。
+モジュールや関数内部での一貫性は、更に重要である。
 
-    しかし、一番重要なことは、いつ一貫性を破るかを知っておくことだ。スタ
-    イルガイドが適用できないことだってある。疑わしいときには、自分自身で
-    最良の判断をすること。前例を見て、最も見栄えがいい方法を判断しなけれ
-    ばならない。それから、尋ねることをためらってはいけない。
+しかし、一番重要なことは、いつ一貫性を破るかを知っておくことだ。
+スタイルガイドが適用できないことだってある。疑わしいときには、
+自分自身で最良の判断をすること。
+前例を見て、最も見栄えがいい方法を判断しなければならない。
+それから、尋ねることをためらってはいけない。
 
-    特定のルールを破る妥当な理由には、次のようなものがある。
+特定のルールを破る妥当な理由には、次の2つがある。
 
-    (1) ルールを適用すると、ソースコードが読みにくくなる。そのルールに沿っ
-        て書かれたソースコードを読むのに慣れている人にとっても、読みにく
-        くなる。
+1. ルールを適用すると、ソースコードが読みにくくなる。
+   そのルールに沿って書かれたソースコードを読むのに慣れている人にとっても、
+   読みにくくなる。
 
-    (2) (歴史的な事情などによって)ルールを破っている既存のソースコード
-        に囲まれている。-- もっとも、この場合は(真の XP に則って)他人
-        の汚いソースコードを、きれいにする機会でもあるけれど。
+2. (歴史的な事情などによって)ルールを破っている既存のソースコードに
+   囲まれている。-- もっとも、この場合は(真の XP に則って)
+   他人の汚いソースコードを、きれいにする機会でもあるけれど。
 
 
 ソースコードのレイアウト
+========================
 
-  インデント
+インデント
+----------
 
-    インデント1段にはスペース4文字を使う。
+インデント1段にはスペース4文字を使う。
 
-    とても古いソースコードを汚したくないなら、スペース 8 個幅のタブを
-    使い続けてもよい。
+とても古いソースコードを汚したくないなら、
+スペース 8 個幅のタブを使い続けてもよい。
 
-    複数行にまたがる場合には、Python の括弧内の要素を暗につなげる方法か、
-    ぶら下がりインデントによって、インデントを揃える。ぶら下がりインデ
-    ントを使うときは、以下の点を考慮する。最初の行については議論の余地
-    はないが、以降は行が継続していることが明確に分かるようにする。
+複数行にまたがる場合には、Python の括弧内の要素を暗につなげる方法か、
+ぶら下がりインデントによって、インデントを揃える。
+ぶら下がりインデントを使うときは、以下の点を考慮する。
+最初の行については議論の余地はないが、
+以降は行が継続していることが明確に分かるようにする。
     
-    
-   ◯:  # デリミタで揃える
+◯::
+
+        # デリミタで揃える
         foo = long_function_name(var_one, var_two,
                                  var_three, var_four)
 
                 var_four):
             print(var_one)
 
-    ×:  # インデントで揃えないなら、最初の行に引数を書いてはならない
+×::
+
+        # インデントで揃えないなら、最初の行に引数を書いてはならない
         foo = long_function_name(var_one, var_two,
             var_three, var_four)
 
             var_four):
             print(var_one)
 
-    △:  # この場合は、余分なインデントをしなくてよい
+△::
+
+         # この場合は、余分なインデントをしなくてよい
          foo = long_function_name(
            var_one, var_two,
            var_three, var_four)
 
-  タブかスペースか
+タブかスペースか
+----------------
 
-    タブとスペースを、決して混在させてはならない。
+タブとスペースを、決して混在させてはならない。
 
-    Python で最も好まれるのは、スペースのみでインデントする方法である。
-    次に人気があるのは、タブのみを使う方法である。タブとスペースが混在
-    させてインデントしているソースコードは、スペースのみを使用したもの
-    に変換するべきだ。Python をコマンドラインから実行するときに、-t オ
-    プションをつけると、ソースコード内にタブとスペースが不正に混在して
-    いる旨を警告してくれる。-tt オプションをつけると、警告ではなくエラー
-    になる。これらのオプションをつけることを強く推奨する!
+Python で最も好まれるのは、スペースのみでインデントする方法である。
+次に人気があるのは、タブのみを使う方法である。タブとスペースが混在
+させてインデントしているソースコードは、スペースのみを使用したもの
+に変換するべきだ。Python をコマンドラインから実行するときに、-t オ
+プションをつけると、ソースコード内にタブとスペースが不正に混在して
+いる旨を警告してくれる。-tt オプションをつけると、警告ではなくエラー
+になる。これらのオプションをつけることを強く推奨する!
 
-    新しいプロジェクトを始める場合には、スペースのみを使う方法が、タブを使う
-    方法よりも、強く推奨されている。ほとんどのエディタは、これを簡単に行
-    う機能がついている。
+新しいプロジェクトを始める場合には、スペースのみを使う方法が、タブを使う
+方法よりも、強く推奨されている。ほとんどのエディタは、これを簡単に行
+う機能がついている。
 
-  一行の最大長さ
+一行の最大長さ
+--------------
 
-    すべての行の最大長さは 79 文字とする。
+すべての行の最大長さは 79 文字とする。
 
-    未だに1行あたり80文字に制限されている機器があるし、ウィンドウ幅を
-    80文字に制限しておけば、複数のウィンドウを横に並べることもできる。
-    古い機器のデフォルトの折り返しは見た目の構造が崩れがちで、その結果、
-    可読性が悪くなる。したがって、すべての行は最大79文字に制限して頂き
-    たい(Emacs はちょうど80文字の長さで折り返す)。長いテキストのブロッ
-    ク(docstring やコメント)に関しては、72文字以下を推奨する。
+未だに1行あたり80文字に制限されている機器があるし、ウィンドウ幅を
+80文字に制限しておけば、複数のウィンドウを横に並べることもできる。
+古い機器のデフォルトの折り返しは見た目の構造が崩れがちで、その結果、
+可読性が悪くなる。したがって、すべての行は最大79文字に制限して頂き
+たい(Emacs はちょうど80文字の長さで折り返す)。長いテキストのブロッ
+ク(docstring やコメント)に関しては、72文字以下を推奨する。
 
-    長い行を折り返す際に望ましいのは、Python が暗に括弧内の行を継続する
-    ことを利用する方法である。必要であれば、式の周りを余分な括弧で囲む
-    ことができるが、バックスラッシュを使う方が見栄えがいい場合もある。
-    継続する行を適切にインデントすることを忘れないように。ブール演算子
-    前後で改行する場合は、演算子の「後」で改行するのが望ましい。以下に
-    例を示す。
+長い行を折り返す際に望ましいのは、Python が暗に括弧内の行を継続する
+ことを利用する方法である。必要であれば、式の周りを余分な括弧で囲む
+ことができるが、バックスラッシュを使う方が見栄えがいい場合もある。
+継続する行を適切にインデントすることを忘れないように。ブール演算子
+前後で改行する場合は、演算子の「後」で改行するのが望ましい。以下に
+例を示す。
 
     class Rectangle(Blob):
 
             Blob.__init__(self, width, height,
                           color, emphasis, highlight)
 
-  空行
+空行
+----
 
-    トップレベルの関数とクラス定義の間は、2 行空ける。
+トップレベルの関数とクラス定義の間は、2 行空ける。
 
-    クラス内部でのメソッド定義の間は 1 行空けること。
+クラス内部でのメソッド定義の間は 1 行空けること。
 
-    関連する関数群の間に、余分な空行
-    を挟んでもよい(控えめに)。関連する1行プログラムのかたまりの間にあ
-    る空行は、省いてもよい。(たとえば、ダミーの実装の集まり)
+関連する関数群の間に、余分な空行を挟んでもよい(控えめに)。
+関連する1行プログラムのかたまりの間にある空行は、省いてもよい
+(たとえば、ダミーの実装の集まり)。
 
-    関数内部でも、論理的な集まりを示すために、控えめに空行を使う。
+関数内部でも、論理的な集まりを示すために、控えめに空行を使う。
 
-    Pythonは、改行文字からControl-L(すなわち^L)を、ホワイトスペースとし
-    て扱う。Emacs(および、いくつかの印刷機器)はこれを改ページとして扱
-    うので、ファイル内部で関連する部分ごとにページを分けるために、これら
-    の文字を使うことができる。
+Pythonは、改行文字からControl-L(すなわち ^L)を、ホワイトスペースとし
+て扱う。Emacs(および、いくつかの印刷機器)はこれを改ページとして扱
+うので、ファイル内部で関連する部分ごとにページを分けるために、これら
+の文字を使うことができる。
+Control-L を改ページとして認識せず、別の文字や記号が表示される、
+エディタやウェブブラウザもあることに注意すること。
 
-  エンコーディング (PEP 263)
+エンコーディング (PEP 263)
+--------------------------
 
-    Python ディストリビューションに含まれるソースコードには、常に ASCII 
-    または Latin-1 エンコーディング (いわゆる ISO-8859-1) を使う。Python 
-    3.0 以降のバージョンでは、Latin-1 よりも UTF-8 が好ましい。PEP 3120 
-    を参照のこと。
+Python ディストリビューションに含まれるソースコードには、常に ASCII 
+または Latin-1 エンコーディング (いわゆる ISO-8859-1) を使う。Python 
+3.0 以降のバージョンでは、Latin-1 よりも UTF-8 が好ましい。PEP 3120 
+を参照のこと。
 
-    ASCII (Python 3.0 の場合には UTF-8) を使用しているファイルではコーディ
-    ングクッキーを記述しない。コメントや docstring の中にLatin-1 エンコー
-    ドが必要な作者名がある場合にのみ、 Latin-1 (または UTF-8) を使う。そ
-    の他、文字列リテラルに非 ASCII 文字列を記述する場合には、\x、\u また
-    は \U でエスケープするの好ましい。
+ASCII (Python 3.0 の場合には UTF-8) を使用しているファイルではコーディ
+ングクッキーを記述しない。コメントや docstring の中にLatin-1 エンコー
+ドが必要な作者名がある場合にのみ、 Latin-1 (または UTF-8) を使う。そ
+の他、文字列リテラルに非 ASCII 文字列を記述する場合には、``\\x`` 、 
+``\\u`` または ``\\U`` でエスケープするのが好ましい。
 
-    Python 3.0 以降の標準ライブラリでは、以下の方針が好ましい(PEP
-    3131 参照)。標準ライブラリの全ての識別子は ASCII のみで書かなけれ
-    ばならず、可能であれば英語を使う(略語や技術用語が英語でないことは
-    多々ある)。ただし (a) 非 ASCII 文字列機能のテストケースと (b) 作者
-    名には、例外的に非 ASCII 文字列を使ってもよい。作者名がラテン・アル
-    ファベットに基づいていない場合には、ラテン文字表記を併記しなければ
-    ならない。
+Python 3.0 以降の標準ライブラリでは、以下の方針が好ましい(PEP
+3131 参照)。標準ライブラリの全ての識別子は ASCII のみで書かなけれ
+ばならず、可能であれば英語を使う(略語や技術用語が英語でないことは
+多々ある)。ただし (a) 非 ASCII 文字列機能のテストケースと (b) 作者
+名には、例外的に非 ASCII 文字列を使ってもよい。作者名がラテン・アル
+ファベットに基づいていない場合には、ラテン文字表記を併記しなければ
+ならない。
 
-    世界中にユーザがいるようなオープンソースプロジェクトでも、同様のポ
-    リシーに準ずることを奨励する。 
+世界中にユーザがいるようなオープンソースプロジェクトでも、同様のポ
+リシーに準ずることを奨励する。 
 
 import
+------
 
-    - import は通常、別々の行に配置するべきである。
+- import は通常、別々の行に配置するべきである。 ::
 
-        ○   import sys
-             import os
+      ○:   import sys
+            import os
 
-        ×   import sys, os
+      ×:   import sys, os
 
-      ただし、以下の記述はかまわない。
+  ただし、以下の記述はかまわない。 ::
 
-        from subprocessimport Poepn, PIPE
+      from subprocessimport Poepn, PIPE
 
-    - import は常に、ファイルの先頭のモジュールのコメントや docstring の
-      後、モジュールのグローバル定義の前に書く。
+- import は常に、ファイルの先頭のモジュールのコメントや docstring の
+  後、モジュールのグローバル定義の前に書く。
 
-      モジュールは以下に示すような順番でまとめておく。
+  モジュールは以下に示すような順番でまとめておく。
 
-      1. 標準ライブラリの import
-      2. 関連するサードパーティの import
-      3. アプリケーションやライブラリ独自の import
+  1. 標準ライブラリの import
+  2. 関連するサードパーティの import
+  3. アプリケーションやライブラリ独自の import
 
-      各グループの間には空行を入れておくこと。
+  各グループの間には空行を入れておくこと。
 
-      __all__ は、import 分より後に記述する。
+  ``__all__`` は、import 分より後に記述する。
 
-    - パッケージ内部の import には、相対 import をしないことが強く推奨さ
-      れている。常に絶対パッケージパスを使用する。PEP 328 [7] は Python 
-      2.5 で完全に実装されているが、暗黙の相対 import は積極的に避けるこ
-      とを推奨する。絶対 import のほうが可搬性があり、一般に可読性が高い。
+- パッケージ内部の import には、相対 import をしないことが強く推奨さ
+  れている。常に絶対パッケージパスを使用する。PEP 328 は Python 2.5 
+  で完全に実装されているが、暗黙の相対 import は積極的に避けるこ
+  とを推奨する。絶対 import のほうが可搬性があり、一般に可読性が高い。
 
-    - クラスを含むモジュールから、クラスを import するときには、通常、次
-      のように書いてもよい。
+- クラスを含むモジュールから、クラスを import するときには、通常、次
+  のように書いてもよい。::
 
-        from myclass import MyClass
-        from foo.bar.yourclass import YourClass
+      from myclass import MyClass
+      from foo.bar.yourclass import YourClass
 
-      上の方法で記述するとローカルの名前が衝突する場合は、次のように書いて、
-      "myclass.MyClass" や "foo.bar.yourclass.YourClass" を使う。
+  上の方法で記述するとローカルの名前が衝突する場合は、次のように書いて、
+  "myclass.MyClass" や "foo.bar.yourclass.YourClass" を使う。
 
-        import myclass
-        import foo.bar.yourclass
+      import myclass
+      import foo.bar.yourclass
+
 
 式や文の中のホワイトスペース
+============================
 
-  悩みの種
+悩みの種
+--------
 
-    以下のような、余分な空白の使用を避ける。
+以下のような、余分な空白の使用を避ける。
 
-    - 括弧のすぐ内側
+- 括弧のすぐ内側
 
       ○ spam(ham[1], {eggs: 2})
       × spam( ham[ 1 ], { eggs: 2 } )
 
-    - コンマ、セミコロン、コロンの直前
+- コンマ、セミコロン、コロンの直前
 
       ○ if x == 4: print x, y; x, y = y, x
       × if x == 4 : print x , y ; x , y = y , x
 
-    - 関数呼び出しで、引数リストが始まる開き括弧の直前
+- 関数呼び出しで、引数リストが始まる開き括弧の直前
 
       ○ spam(1)
       × spam (1)
 
-    - インデックスやスライスが始まる開き括弧の直前
+- インデックスやスライスが始まる開き括弧の直前
 
       ○ dict['key'] = list[index]
       × dict ['key'] = list [index]
 
-    - 代入演算子(または他の演算子)のまわりに、1文字以上のスペースを配
-      置して、別の式と列揃えをすること。
+- 代入演算子(または他の演算子)のまわりに、1文字以上のスペースを配
+  置して、別の式と列揃えをすること。
 
-    
+  ○::
 
-          x = 1
-          y = 2
-          long_variable = 3
+      x = 1
+      y = 2
+      long_variable = 3
 
-      ×
+  ×::
 
-          x             = 1
-          y             = 2
-          long_variable = 3
+      x             = 1
+      y             = 2
+      long_variable = 3
 
-  その他の推奨案
+その他の推奨案
+--------------
 
-    - バイナリ演算子の両側は、常にスペース1個で挟む。代入演算子(=)、
-      拡張代入演算子 (+=、 -= など)、比較演算子(==, <, >, !=, <>, <=, 
-      >=, in, not in, is, is not)、ブール演算子(and, or, not)に適用す
-      る。
+- バイナリ演算子の両側は、常にスペース1個で挟む。代入演算子( ``=`` )、
+  拡張代入演算子 (``+=``、 ``-=`` など)、
+  比較演算子( ``==`` , ``<`` , ``>`` , ``!=`` , ``<>``, ``<=``, ``>=``,
+  ``in``, ``not in``, ``is``, ``is not``)、
+  ブール演算子(``and``, ``or``, ``not``)に適用する。
 
-    - 算術演算子の前後にスペースを置く。
+- 算術演算子の前後にスペースを置く。
 
-    
+  ○::
 
-          i = i + 1
-          submitted += 1
-          x = x * 2 - 1
-          hypot2 = x * x + y * y
-          c = (a + b) * (a - b)
+      i = i + 1
+      submitted += 1
+      x = x * 2 - 1
+      hypot2 = x * x + y * y
+      c = (a + b) * (a - b)
 
-      ×
+  ×::
 
-          i=i+1
-          submitted +=1
-          x = x*2 - 1
-          hypot2 = x*x + y*y
-          c = (a+b) * (a-b)
+      i=i+1
+      submitted +=1
+      x = x*2 - 1
+      hypot2 = x*x + y*y
+      c = (a+b) * (a-b)
 
-    - '=' 記号を、キーワード引数やデフォルトのパラメータ値として使う場合、
-      '='記号の両側にスペースを配置しないこと。
+- ``=`` 記号を、キーワード引数やデフォルトのパラメータ値として使う場合、
+  ``=`` 記号の両側にスペースを配置しないこと。
 
-    
+  ○::
 
-          def complex(real, imag=0.0):
-              return magic(r=real, i=imag)
+      def complex(real, imag=0.0):
+          return magic(r=real, i=imag)
 
-      ×
+  ×::
 
-          def complex(real, imag = 0.0):
-              return magic(r = real, i = imag)
+      def complex(real, imag = 0.0):
+          return magic(r = real, i = imag)
 
-    - 複文(1行に書かれた複数の文)は書かないことが推奨されている。
+- 複文(1行に書かれた複数の文)は書かないことが推奨されている。
 
-    
+  ○::
 
-          if foo == 'blah':
-              do_blah_thing()
-          do_one()
-          do_two()
-          do_three()
+      if foo == 'blah':
+          do_blah_thing()
+      do_one()
+      do_two()
+      do_three()
 
-  
+  どちらかというと×::
 
-          if foo == 'blah': do_blah_thing()
-          do_one(); do_two(); do_three()
+      if foo == 'blah': do_blah_thing()
+      do_one(); do_two(); do_three()
 
-    - if、for、while ブロックの中身が小さいときには 1 行で書いてもよい。
-      ただし、複文の場合には 1 行で書いてはならない。
+- if、for、while ブロックの中身が小さいときには 1 行で書いてもよい。
+  ただし、複文の場合には 1 行で書いてはならない。
+  それから、こういう長い行を、途中で改行しないこと!
 
-  
+  どちらかというと×::
 
-          if foo == 'blah': do_blah_thing()
-          for x in lst: total += x
-          while t < 10: t = delay()
+      if foo == 'blah': do_blah_thing()
+      for x in lst: total += x
+      while t < 10: t = delay()
 
-      ×
+   ダメ絶対!::
 
-          if foo == 'blah': do_blah_thing()
-          else: do_non_blah_thing()
+      if foo == 'blah': do_blah_thing()
+      else: do_non_blah_thing()
 
-          try: something()
-          finally: cleanup()
+      try: something()
+      finally: cleanup()
 
-          do_one(); do_two(); do_three(long, argument,
-                                       list, like, this)
+      do_one(); do_two(); do_three(long, argument,
+                                   list, like, this)
 
-          if foo == 'blah': one(); two(); three()
+      if foo == 'blah': one(); two(); three()
 
 コメント
+========
 
-    ソースコードと矛盾するコメントは、コメントが無いよりも問題である。
-    ソースコードを変更したときには、コメントを更新することを優先するよう
-    に。
+ソースコードと矛盾するコメントは、コメントが無いよりも問題である。
+ソースコードを変更したときには、コメントを更新することにも重きを置くように。
 
-    コメントは完全な文で書くべきである。コメントが句や文である場合、小文
-    字で始まる識別子である場合を除いて、最初の文字は大文字で書くべきで
-    ある(識別子の大文字小文字は絶対に変えてはいけない)。
+コメントは完全な文で書くべきである。コメントが句や文である場合、小文
+字で始まる識別子である場合を除いて、最初の文字は大文字で書くべきで
+ある(識別子の大文字小文字は絶対に変えてはいけない)。
 
-    短いコメントなら、最後のピリオドは省くのがよい。ブロックコメントは通
-    常、1つまたはそれ以上の段落の中に完全な文で構成しておいて、各文の最
-    後にはピリオドを打っておく。
+短いコメントなら、最後のピリオドは省くのがよい。ブロックコメントは通
+常、1つまたはそれ以上の段落の中に完全な文で構成しておいて、各文の最
+後にはピリオドを打っておく。
 
-    文末のピリオドの後には、スペースをふたつ配置する。
+文末のピリオドの後には、スペースをふたつ配置する。
 
-    英語を書くときには、W. Strunk と E. White による「The Element of 
-     Style」が役に立つ。
+英語を書くときには、W. Strunk と E. White による「The Element of 
+Style」が役に立つ。
 
-    英語を母国語としない Pythonプログラマの方々へ。あなたの母国語を話さ
-    ない人が、そのソースコードを決して読まないことを、120%確信できる場
-    合を除いて、コメントは英語で書いていただきたい。
+英語を母国語としない Pythonプログラマの方々へ。あなたの母国語を話さ
+ない人が、そのソースコードを決して読まないことを、120%確信できる場
+合を除いて、コメントは英語で書いていただきたい。
 
-  ブロックコメント
+ブロックコメント
+----------------
 
-    ブロックコメントは、通常、後続するソースコードの一部(あるいはすべて)
-    に関する説明であり、字下げの幅をソースコードに合わせて書く。ブロック
-    コメントの各行は、# とスペース1つで始まる(コメント内のテキストが字
-    下げをしていない限り)。
+ブロックコメントは、通常、後続するソースコードの一部(あるいはすべて)
+に関する説明であり、字下げの幅をソースコードに合わせて書く。ブロック
+コメントの各行は、# とスペース1つで始まる(コメント内のテキストが字
+下げをしていない限り)。
 
-  インラインコメント
+インラインコメント
+------------------
 
-    インラインコメントは控えめに使う。
+インラインコメントは控えめに使う。
 
-    インラインコメントは、文と同じ行に入れるコメントである。インライン
-    コメントは、控えめに使う。コメントは、文から少なくともスペース2個分
-    離しておき、# とスペース1個で始まるようにするべきである。
+インラインコメントは、文と同じ行に入れるコメントである。インライン
+コメントは、控えめに使う。コメントは、文から少なくともスペース2個分
+離しておき、# とスペース1個で始まるようにするべきである。
 
-    分かりきったことを書くくらいなら、インラインコメントは不要で、むしろ
-    気が散るものである。次のようなことを書かないように。
+分かりきったことを書くくらいなら、インラインコメントは不要で、むしろ
+気が散るものである。次のようなことを書かないように。::
 
-        x = x+1                 # Increment x
+    x = x + 1                 # Increment x
 
-    しかし場合によっては、次のようなコメントは有用である。
+しかし場合によっては、次のようなコメントは有用である。::
 
-        x = x+1                 # Compensate for border
-
+    x = x + 1                 # Compensate for border
 
 ドキュメンテーション文字列
+--------------------------
 
-    良いドキュメンテーション文字列(以下 docstring)の書き方の様式に関し
-    ては、docstring に関する PEP 257 [3]が、非常に参考になる。
+良いドキュメンテーション文字列(以下 docstring)の書き方の様式に関し
+ては、docstring に関する PEP 257 が、非常に参考になる。
 
-    - すべての公開モジュール、関数、クラス、メソッドには docstring を記
-      述すること。非公開メソッドに docstring は必要ではないが、そのメ
-      ソッドが何をするかコメントしておくべきである。このコメントは def 
-      行の直後に書いておくこと。
+- すべての公開モジュール、関数、クラス、メソッドには docstring を記
+  述すること。非公開メソッドに docstring は必要ではないが、そのメ
+  ソッドが何をするかコメントしておくべきである。このコメントは ``def``
+  行の直後に書いておくこと。
 
-    - PEP 257 には、docstring のよい慣例について書いてある。複数行に渡る 
-      docstring の最後の """ は、単独の行に書くというのが、最重要事項で
-      ある。
+- PEP 257 には、docstring のよい慣例について書いてある。複数行に渡る 
+  docstring の最後の ``"""`` は、単独の行に書くというのが、最重要事項で
+  ある。::
 
       """Return a foobang
 
       Optional plotz says to frobnicate the bizbaz first.
       """
 
-    - 1行の docstring では、最後の """ が同じ行にあってもよい。
+- 1行の docstring では、最後の """ が同じ行にあってもよい。
 
 
 バージョンの記録
+================
 
-    ソースファイル内にSubversion、CVS、RCSなどの情報を持たせる必要があ
-    る場合には、以下のようにする。
+ソースファイル内にSubversion、CVS、RCSなどの情報を持たせる必要があ
+る場合には、以下のようにする。::
 
-        __version__ = "$Revision$"
-        # $Source$
+    __version__ = "$Revision$"
+    # $Source$
 
-    これらの行はモジュールのdocstringより後ろ、その他のソースコードより
-    前に、空行で分離して書いておく。
+これらの行はモジュールのdocstringより後ろ、その他のソースコードより
+前に、空行で分離して書いておく。
 
 
 命名規則
+========
 
-    Pythonライブラリの命名規則は、少しごちゃごちゃしているため、完全に一
-    貫性を保つことはできない。しかし、ここに現在、推奨されている標準命名
-    規則を示しておく。 
+Pythonライブラリの命名規則は、少しごちゃごちゃしているため、完全に一
+貫性を保つことはできない。しかし、ここに現在、推奨されている標準命名
+規則を示しておく。 
+新たに開発するモジュールやパッケージ(サードパーティのフレームワーク
+も含む)はこの規則にしたがって書くべきである。ただし、既存のライブラ
+リが異なったスタイルで書いてあれば、内部での一貫性を優先する。
 
-    新たに開発するモジュールやパッケージ(サードパーティのフレームワーク
-    も含む)はこの規則にしたがって書くべきである。ただし、既存のライブラ
-    リが異なったスタイルで書いてあれば、内部での一貫性を優先する。
 
+記述方法:命名のスタイル
+------------------------
 
-  記述方法:命名のスタイル
+様々な命名スタイルが存在する。どの場面で使われるかとは別に、どんな命
+名スタイルが使われているか知っておくと便利だろう。
 
-    様々な命名スタイルが存在する。どの場面で使われるかとは別に、どんな命
-    名スタイルが使われているか知っておくと便利だろう。
+以下のような命名スタイルが、よく見受けられる。
 
-    以下のような命名スタイルが、よく見受けられる。
-
-    - b (小文字1文字)
-
-    - B (大文字1文字)
-
-    - lowercase
-
-    - lower_case_with_underscores
-
-    - UPPERCASE
-
-    - UPPER_CASE_WITH_UNDERSCORES
-
-    - CapitalizedWords (CapWords、字面のでこぼこ具合から CamelCase [4]、
+- ``b`` (小文字1文字)
+- ``B`` (大文字1文字)
+- ``lowercase``
+- ``lower_case_with_underscores``
+- ``UPPERCASE``
+- ``UPPER_CASE_WITH_UNDERSCORES``
+- ``CapitalizedWords`` (CapWords、字面のでこぼこ具合から CamelCase [4]_ 、
       StudlyCaps とも )StudlyCaps とも呼ばれる。
 
-      注意:CapWords で略語を使うとき、略した文字をすべて大文字表記する。
-      したがって、HttpServerError よりも HTTPServerError のほうが良い。
+  注意:CapWords で略語を使うとき、略した文字をすべて大文字表記する。
+  したがって、HttpServerError よりも HTTPServerError のほうが良い。
+- mixedCase (1文字目が小文字というのが、CapitalizedWords との違い)
+- Capitalized_Words_With_Underscores (汚い)
 
-    - mixedCase (1文字目が小文字というのが、CapitalizedWords との違い)
+関連する名前をグループ化するために、短いプレフィックス(接頭辞)をつ
+けるというスタイルもある。Pythonで、このスタイルはあまり用いられない
+が、念のため記しておく。たとえば、``os.stat()`` 関数は、伝統的に ``st_mode`` 、
+``st_size`` 、 ``st_mtime`` というような名前を持つタプルを返す。
+X11ライブラリのパブリック関数の先頭には、Xが使われる。(POSIX に慣れているプロ
+グラマに対して、POSIX システムコールで使う構造体と一致していること
+を強調するため、このような変数名を採用している)
 
-    - Capitalized_Words_With_Underscores (汚い)
+X11 ライブラリでは、全ての公開関数名に X が接頭している。一般に 
+Python では、このスタイルは必要ないだろう。なぜなら、属性やメソッド
+の名前では、オブジェクト名がプレフィックスになり、関数の名前ではモジュー
+ル名がプレフィックスとなる。
 
-    関連する名前をグループ化するために、短いプレフィックス(接頭辞)をつ
-    けるというスタイルもある。Pythonで、このスタイルはあまり用いられない
-    が、念のため記しておく。たとえば、os.stat()関数は、伝統的にst_mode、
-    st_size、st_mtime というような名前を持つタプルを返す。X11ライブラリ
-    のパブリック関数の先頭には、Xが使われる。(POSIX に慣れているプロ
-    グラマに対して、POSIX システムコールで使う構造体と一致していること
-    を強調するため、このような変数名を採用している)
+更に、名前の最初や最後にアンダースコアをつけた特別な形式も、見受けら
+る。(大文字・小文字の規則も一緒に適用される)
 
-    X11 ライブラリでは、全ての公開関数名に X が接頭している。一般に 
-    Python では、このスタイルは必要ないだろう。なぜなら、属性やメソッド
-    の名前では、オブジェクト名がプレフィックスになり、関数の名前ではモジュー
-    ル名がプレフィックスとなる。
+- ``_single_leading_underscore``: 弱い内部使用の識別子。たとえば、
+  "from M import *" は、アンダースコア1つで始まる名前のオブジェクト
+  を、importしない。
 
-    更に、名前の最初や最後にアンダースコアをつけた特別な形式も、見受けら
-    る。(大文字・小文字の規則も一緒に適用される)
-
-    - _single_leading_underscore:弱い内部使用の識別子。たとえば、
-      "from M import *" は、アンダースコア1つで始まる名前のオブジェクト
-      を、importしない。
-
-    - single_trailing_underscore_: Pythonの予約語との衝突を避けるための
-      規則として使う。たとえば、
+- ``single_trailing_underscore_`` : Pythonの予約語との衝突を避けるための
+      規則として使う。たとえば ::
 
       Tkiner.Toplevel(master, class_="ClassName"))
+
+- ``__double_leading_underscore``: クラスの属性に使用すると、名前修飾が起こる。
+  (FooBar クラス内では、 __boo は、 _FooBar__boo となる。後述。)
       
-    - __double_leading_and_trailing_underscore__: ユーザがコントロール
-      する名前空間内での、マジック・オブジェクトまたはマジック属性。たと
-      えば、__init__、 __import__ 、__file__。 この命名規則を、新たに作っ
-      てはならない。必要な場合には、ドキュメント化して使う。
+- ``__double_leading_and_trailing_underscore__``: ユーザがコントロール
+  する名前空間内での、マジック・オブジェクトまたはマジック属性。たと
+  えば、__init__、 __import__ 、__file__。 この命名規則を、新たに作っ
+  てはならない。必要な場合には、ドキュメント化して使う。
 
-  規範:命名規則
+規範:命名規則
+--------------
 
-    避けるべき名前
+避けるべき名前
+~~~~~~~~~~~~~~
 
-      「l」 (小文字のエル)、「O」(大文字のオー)、「I」(大文字のアイ)
-      を1文字の変数名として使わない。
+「l」 (小文字のエル)、「O」(大文字のオー)、「I」(大文字のアイ)
+を1文字の変数名として使わない。
 
-      フォントによっては、これらの文字は数字の 1 や 0 と区別できない。
-     「l」 を使いたくなったら、代わりに「L」を使う。
+フォントによっては、これらの文字は数字の 1 や 0 と区別できない。
+l」 を使いたくなったら、代わりに「L」を使う。
 
-    パッケージ名とモジュール名
+パッケージ名とモジュール名
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      モジュール名には、アンダースコアを含まない短い lowercase を使う。
+モジュール名には、アンダースコアを含まない短い lowercase を使う。
+可読性が高まるのであれば、アンダースコアを使ってもよい。
+パッケージ名にも、短い lowercase で命名するが、
+アンダースコアを使うのは非推奨である。
 
-      モジュール名は、ファイル名に反映される。ところが、ファイルシステム
-      によっては、大文字・小文字の区別をしなかったり、長い名前をはしょっ
-      てしまうので、モジュール名は短く、かつ、大文字・小文字が違うだけで
-      他のモジュール名と衝突しないように、選ぶことが重要である。 これは
-      Unixでは問題にならないが、そのソースコードを古い Mac や Windows や 
-      DOS に持っていったときに問題となる。
+モジュール名は、ファイル名に反映される。ところが、ファイルシステム
+によっては、大文字・小文字の区別をしなかったり、長い名前をはしょっ
+てしまうので、モジュール名は短く、かつ、大文字・小文字が違うだけで
+他のモジュール名と衝突しないように、選ぶことが重要である。 これは
+Unix では問題にならないが、そのソースコードを古い Mac や Windows や 
+DOS に持っていったときに問題となる。
 
-      C や C++で書かれた拡張モジュールがあって、それに伴うPythonモジュール
-      が、より高レベル(たとえば、よりオブジェクト指向)なインターフェー
-      スを提供するときには、すべて小文字にして先頭にアンダースコアをつけ
-      る(たとえば、_socket)。
+C や C++で書かれた拡張モジュールがあって、それに伴うPythonモジュール
+が、より高レベル(たとえば、よりオブジェクト指向)なインターフェースを
+提供するときには、すべて小文字にして先頭にアンダースコアをつける
+(たとえば、 ``_socket`` )。
 
-    クラス名
+クラス名
+~~~~~~~~
 
-      ほぼ例外なく、クラス名にはCapWords方式を使う。内部使用のクラス名に
-      は、先頭にアンダースコアを追加する。
+ほぼ例外なく、クラス名にはCapWords方式を使う。内部使用のクラス名に
+は、先頭にアンダースコアを追加する。
 
-    例外名
+例外名
+~~~~~~
 
-      例外はクラスなので、クラスの命名規則を適用する。ただし、「Error」
-      を接尾する(もしその例外が実際にエラーであるなら)。
+例外はクラスなので、クラスの命名規則を適用する。ただし、「Error」
+を接尾する(もしその例外が実際にエラーであるなら)。
 
-    グローバル変数名
+グローバル変数名
+~~~~~~~~~~~~~~~~
 
-      (これらの変数は1つのモジュール内でのみ使われるものだと、願いま
-       しょう)関数とほぼ同じ規則を適用する。
+(これらの変数は1つのモジュール内でのみ使われるものだと、願いま
+しょう)関数とほぼ同じ規則を適用する。
 
-       "from M import *" を通して使用されるように設計されたモジュールで
-       は、__all__ のしくみを使って、グローバル変数がエクスポートされな
-       いようにする。あるいは、古い規則であるアンダースコア付きの接頭辞
-       をつける(非公開のモジュール変数を意味する)。
+"from M import *" を通して使用されるように設計されたモジュールで
+は、__all__ のしくみを使って、グローバル変数がエクスポートされな
+いようにする。あるいは、古い規則であるアンダースコア付きの接頭辞
+をつける(非公開のモジュール変数を意味する)。
 
-    関数名
+関数名
+~~~~~~
 
-      関数名は lowercase 方式で命名し、可読性のためにアンダースコアで単
-      語を区切ってもよい。
+関数名は lowercase 方式で命名し、可読性のためにアンダースコアで単
+語を区切ってもよい。
 
-      mixedCase 方式は、既に広く使われているような文脈(たとえば 
-      threading.py)で、互換性を保つ場合にのみ許される。
+mixedCase 方式は、既に広く使われているような文脈(たとえば 
+threading.py)で、互換性を保つ場合にのみ許される。
 
-    関数やメソッドの引数
+関数やメソッドの引数
+~~~~~~~~~~~~~~~~~~~~
 
-      インスタンスメソッドの第 1 引数には、常にselfを使う。
+インスタンスメソッドの第 1 引数には、常に ``self`` を使う。
 
-      クラスメソッドの第 1 引数には、常に「cls」を使う。
+クラスメソッドの第 1 引数には、常に ``cls`` を使う。
 
-      引数の名前が、予約語と衝突する場合、略語や変な綴りよりも、末尾にア
-      ンダースコアをつけるのが一般によいとされる。したがって、「prnt」よ
-      りも「print_」 のほうがよい(おそらく、もっと良い方法は、同意語を
-      使って名前の衝突を避けることだろう)。
+引数の名前が、予約語と衝突する場合、略語や変な綴りよりも、末尾にア
+ンダースコアをつけるのが一般によいとされる。したがって、 ``clss``
+よりも ``classs_`` のほうがよい(おそらく、もっと良い方法は、同意語を
+使って名前の衝突を避けることだろう)。
 
-    メソッド名とインスタンス変数
+メソッド名とインスタンス変数
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-      関数の場合と同じルールを使う。lowercase 方式で命名し、可読性を上げ
-      るためにアンダースコアで単語を区切る。
+関数の場合と同じルールを使う。lowercase 方式で命名し、可読性を上げ
+るためにアンダースコアで単語を区切る。
 
-      非公開なメソッドとインスタンス変数にのみ、先頭にアンダースコアを1
-      つ使って命名する。
+非公開なメソッドとインスタンス変数にのみ、先頭にアンダースコアを1
+つ使って命名する。
 
-      サブクラスとの名前の衝突を避けるには、先頭にアンダースコアを2つ付
-      けることで、Python の名前修飾ルールが行われる。
+サブクラスとの名前の衝突を避けるには、先頭にアンダースコアを2つ付
+けることで、Python の名前修飾ルールが行われる。
 
-      Python は先頭にアンダースコアが2つあるような名前があると、クラス名
-      で修飾する。Foo クラスに __a という属性があると、Foo.__a という形
-      式でアクセスすることはできない(Foo._Foo__a でアクセスできるけれど)。
-      一般に、先頭に2つのアンダースコアがついた名前は、サブクラス化され
-      るクラスにおいて名前が衝突するのを避けるために仕様するべきである。
+Python は先頭にアンダースコアが2つあるような名前があると、クラス名
+で修飾する。Foo クラスに ``__a`` という属性があると、 ``Foo.__a`` という形
+式でアクセスすることはできない( ``Foo._Foo__a`` でアクセスできるけれど)。
+一般に、先頭に2つのアンダースコアがついた名前は、サブクラス化され
+るクラスにおいて名前が衝突するのを避けるために仕様するべきである。
 
-      注意:__names の使い方には、議論の余地がある(後述)。
+注意:__names の使い方には、議論の余地がある(後述)。
 
-    定数
+定数
+~~~~
 
-      定数はモジュールのレベルで定義し、アンダースコアで単語を分割した
-      大文字で表記する。たとえば MAX_OVERFLOW、TOTAL。
+定数はモジュールのレベルで定義し、アンダースコアで単語を分割した
+大文字で表記する。たとえば ``MAX_OVERFLOW`` 、 ``TOTAL`` 。
 
-    継承のための設計
+継承のための設計
+~~~~~~~~~~~~~~~~
 
-      クラスのメソッドやインスタンス変数(つまり「属性」)を公開すること
-      の是非を、常に考慮する。どちらがいいか分からないときには、非公開に
-      する。公開属性を非公開にするよりも、非公開属性を公開にするほうが容
-      易である。
+クラスのメソッドやインスタンス変数(つまり「属性」)を公開すること
+の是非を、常に考慮する。どちらがいいか分からないときには、非公開に
+する。公開属性を非公開にするよりも、非公開属性を公開にするほうが容
+易である。
 
-      公開属性にするということは、あなたのクラスを他人が使うことを想定し、
-      将来の非互換性を避けることを約束したということだ。非公開属性にする
-      ということは、他人が使うことを想定しておらず、変更したり削除したり
-      するかも知れないということだ。
+公開属性にするということは、あなたのクラスを他人が使うことを想定し、
+将来の非互換性を避けることを約束したということだ。非公開属性にする
+ということは、他人が使うことを想定しておらず、変更したり削除したり
+するかも知れないということだ。
 
-      ここでは「プライベート」という表現をしない。Python では(たくさん
-      の不要な作業なしで)真のプライベート属性を持たせられないからだ。
+ここでは「プライベート」という表現をしない。Python では(たくさん
+の不要な作業なしで)真のプライベート属性を持たせられないからだ。
 
-      他の属性として、「サブクラスの API」(しばしば他の言語では
-     「protected」と呼ばれる)がある。クラスの中には継承されるために設計
-      されるものがあり、クラスのふるまいの様相を拡張したり、変更したりさ
-      れる。このようなクラスを設計するとき、どの属性を public にし、どの
-      属性をサブクラスの API にし、どの属性を基底クラスのみで使うのか、
-      明示的に意思決定する。
+他の属性として、「サブクラスの API」(しばしば他の言語では
+protected」と呼ばれる)がある。クラスの中には継承されるために設計
+されるものがあり、クラスのふるまいの様相を拡張したり、変更したりさ
+れる。このようなクラスを設計するとき、どの属性を public にし、どの
+属性をサブクラスの API にし、どの属性を基底クラスのみで使うのか、
+明示的に意思決定する。
 
-      以上を踏まえた、Python 的なガイドラインは以下のとおりである。
+以上を踏まえた、Python 的なガイドラインは以下のとおりである。
 
-      - 公開属性の先頭にはアンダースコアをつけない。
+- 公開属性の先頭にはアンダースコアをつけない。
 
-      - 公開属性の名前が予約語と衝突する場合、名前の最後にアンダースコア
-        をひとつつける。これは、略称や崩した綴りよりも、好まれる方法だ。
-       (ただし、クラスだと分かっているときには、引数や変数には「cls」が
-        よい。特にクラスメソッドの第1引数には。)
+- 公開属性の名前が予約語と衝突する場合、名前の最後にアンダースコア
+  をひとつつける。これは、略称や崩した綴りよりも、好まれる方法だ。
+ (ただし、クラスだと分かっているときには、引数や変数には「cls」が
+  よい。特にクラスメソッドの第1引数には。)
 
-        注1: クラスメソッドについては、上述の引数名の推奨案を参照のこと。
+  注1: クラスメソッドについては、上述の引数名の推奨案を参照のこと。
 
-      - 単純な公開データ属性には、複雑なアクセッサまたはミューテータメソッ
-        ドではなく、属性の名前を公表するのが最善である。単純なデータ属性
-        が、機能的なふるまいをするよう変更しなければならないとき、
-        Pythhon が将来の拡張が容易な方法を提供していることを思い出そう。
-        こんなときには、properties を使って、単純なデータ属性にアクセス
-        する文法のまま、機能の実装を隠すことができる。
+- 単純な公開データ属性には、複雑なアクセッサまたはミューテータメソッ
+  ドではなく、属性の名前を公表するのが最善である。単純なデータ属性
+  が、機能的なふるまいをするよう変更しなければならないとき、
+  Python が将来の拡張が容易な方法を提供していることを思い出そう。
+  こんなときには、properties を使って、単純なデータ属性にアクセス
+  する文法のまま、機能の実装を隠すことができる。
 
-        注1: properties は新しいスタイルのクラスでのみ使える。
+  注1: properties は新しいスタイルのクラスでのみ使える。
 
-        注2: 関数のふるまいが、副作用を起こさないように努めること。ただ
-        し、キャッシュのような副作用は一般的に問題ない。
+  注2: 関数のふるまいが、副作用を起こさないように努めること。ただ
+  し、キャッシュのような副作用は一般的に問題ない。
 
-        注3: 計算量が多い処理に properties を使うのを避ける。この表記方
-        法を見ると、アクセスするのが(比較的)計算量が少ない処理であるよ
-        うに見えるからだ。
+  注3: 計算量が多い処理に properties を使うのを避ける。この表記方
+  法を見ると、アクセスするのが(比較的)計算量が少ない処理であるよ
+  うに見えるからだ。
 
-      - サブクラス化して使うことを意図したクラスがあって、かつ、そのクラ
-        スにはサブクラスから使って欲しくない属性があるときには、先頭にふ
-        たつアンダースコアをつけて、末尾にアンダースコアをつけない属性名
-        にできないか考える。こうしておくと、Python の名前修飾アルゴリズ
-        ムが、属性名をクラス名で修飾するようになる。不用意にもサブクラス
-        に同じ名前を属性を作って、名前が衝突する、という事態を避けられる。
+- サブクラス化して使うことを意図したクラスがあって、かつ、そのクラ
+  スにはサブクラスから使って欲しくない属性があるときには、先頭にふ
+  たつアンダースコアをつけて、末尾にアンダースコアをつけない属性名
+  にできないか考える。こうしておくと、Python の名前修飾アルゴリズ
+  ムが、属性名をクラス名で修飾するようになる。不用意にもサブクラス
+  に同じ名前を属性を作って、名前が衝突する、という事態を避けられる。
 
-        注1: 単純なクラス名を使って名前修飾が行われることに注意する。つ
-        まり、サブクラスで、スーパークラスと同じクラス名で同じ属性名を使
-        うと、名前の衝突は起こる。
+  注1: 単純なクラス名を使って名前修飾が行われることに注意する。つ
+  まり、サブクラスで、スーパークラスと同じクラス名で同じ属性名を使
+  うと、名前の衝突は起こる。
 
-        注2: 名前修飾のせいで、デバッグや __getattr__() が不便になること
-        がある。しかし、名前修飾のアルゴリズムはきちんと文書化されている
-        し、手作業で処理するのは簡単である。
+  注2: 名前修飾のせいで、デバッグや ``__getattr__()`` が不便になること
+  がある。しかし、名前修飾のアルゴリズムはきちんと文書化されている
+  し、手作業で処理するのは簡単である。
 
-        注3: 名前修飾はみんなに好かれているわけではない。呼び出し側で使っ
-        ている名前と、名前修飾された変数名が偶然衝突することもある。属性
-        隠蔽と名前衝突のバランスを取るよう努めてほしい。
+  注3: 名前修飾はみんなに好かれているわけではない。呼び出し側で使っ
+  ている名前と、名前修飾された変数名が偶然衝突することもある。属性
+  隠蔽と名前衝突のバランスを取るよう努めてほしい。
 
 プログラミングにおける推奨案
+============================
 
-    - ソースコードは Python の実装(PyPy、Jython、IronPython、Pyrex、
-      Psyco など)ごとの欠点を引き出さないように書くべきである。たとえば、
-      CPython が a+=b や a=a+b などの文字列連結をインプレイス処理して、効
-      率よく動作する実装に依存してはならない。これでは Jython での動作が遅く
-      なってしまう。パフォーマンスに敏感な部分では、''.join() を使うべき
-      である。こう書いておけば、様々な実装において、連結処理は線形時間で
-      処理できる。
+- ソースコードは Python の実装(PyPy、Jython、IronPython、Pyrex、
+  Psyco など)ごとの欠点を引き出さないように書くべきである。
+  
+  たとえば、CPython が ``a += b`` や ``a = a + b`` などの文字列連結を
+  インプレイス処理して、効率よく動作する実装に依存してはならない。
+  これでは Jython での動作が遅くなってしまう。
+  パフォーマンスに敏感な部分では、 ``''.join()`` を使うべき
+  である。こう書いておけば、様々な実装において、連結処理は線形時間で
+  処理できる。
 
-    - None のようなシングルトンとの比較には、いつも「is」や「is not」を
-      使うべきである。
+- None のようなシングルトンとの比較には、いつも ``is`` や ``is not`` を
+  使うべきである。
 
-      また「if x is not None」という条件を意図して「if x」と書くことは避
-      けること。たとえば、デフォルトで None が代入される変数や引数に、他
-      の値を持っていることをテストするときに使える。他の値には、False も
-      含まれることに注意。
+  また ``if x is not None`` という条件を意図して ``if x`` と書くことは避
+  けること。たとえば、デフォルトで None が代入される変数や引数に、他
+  の値を持っていることをテストするときに使える。他の値には、False も
+  含まれることに注意。
 
-    - クラスを使った例外は、文字列を使った例外よりも望ましい。
+- 比較演算によって、順序演算を実装するときには、呼び出し側が一部の
+  演算だけを使うと仮定せず、6種類全部
+   (``__eq__``, ``__ne__``, ``__lt__``, ``__le__``, ``__gt__``, ``__ge__``, )
+  を実装するのがベストだ。
+  
+  しんどい思いを避けるために ``functools.total_ordering()`` デコレータを使えば、
+  不足している演算メソッドを生成してくれる。
+  
+  PEP 207 によると、Python ではリフレキシビリティが想定されている。
+  したがって、インタプリタは ``y > x`` と ``x < y`` 、 
+  ``y >= x`` と ``x <= y`` 、``x == y`` と ``x != y`` 
 
-      新しいコードでは、文字列による例外は禁止されている。文字列例外が 
-      Python 2.6 で取り除かれているからだ。
+- 例外はクラスで実装する。
 
-      モジュールやパッケージでは、ドメイン独自の基底例外クラスを定義して
-      おき、これは組み込みの Exception クラスを継承しておくべきである。
-      常にクラスの docstring を入れておくこと。以下に例を示す。
+  新しいコードでは、文字列による例外は禁止されている。文字列例外が 
+  Python 2.6 で取り除かれているからだ。
 
-        class MessageError(Exception):
-            """Base class for errors in the email package."""
+  モジュールやパッケージでは、ドメイン独自の基底例外クラスを定義して
+  おき、これは組み込みの Exception クラスを継承しておくべきである。
+  常にクラスの docstring を入れておくこと。以下に例を示す。::
 
-      ここでは、クラスの命名規則を適用する。ただし、エラーである場合には、
-      その例外クラス名の最後に "Error" をつけておく。エラーでない例外の
-      場合には、特別な接尾辞は必要ない。
+    class MessageError(Exception):
+        """Base class for errors in the email package."""
 
-    -  例外を発行するとき、古い表記の「raise ValueError, 'message'」では
-      なく 「raise ValueError('message')」を使用する。例外の引数が長かっ
-      たり、フォーマッティングしたりするとき、行継続の「\」記号を使用し
-      なくてよいので、括弧を使う表記法が好ましい。古い表記は Python 3000 
-      で除外される。
+  ここでは、クラスの命名規則を適用する。ただし、エラーである場合には、
+  その例外クラス名の最後に "Error" をつけておく。エラーでない例外の
+  場合には、特別な接尾辞は必要ない。
 
-    - 例外を捕捉するとき、'except:' と裸で受け取るのではなく、可能であれ
-      ばどの例外を捕捉するのか明示する。
+  例外を発行するとき、古い表記の ``raise ValueError, 'message`` では
+      なく ``raise ValueError('message')`` を使用する。
+	  
+  例外の引数が長かったり、フォーマッティングしたりするとき、
+  行継続の「\」記号を使用しなくてよいという点で、括弧を使う表記法が好ましい。
+  古い表記は Python 3 で除外される。
 
-      以下に例を示す。
+- 例外を捕捉するとき、 ``except:`` と裸で受け取るのではなく、可能であれ
+  ばどの例外を捕捉するのか明示する。
+
+  以下に例を示す。::
 
           try:
-              import platform_specific_module
+		      import platform_specific_module
           except ImportError:
               platform_specific_module = None 
 
-      裸の 'except:' 節は、SystemExit と KeyboardInterrupt を補足するの
-      で、Control-C でプログラムを停止させるのが難しくなり、他の問題が隠
-      れてしまう。プログラムのエラーを知らせるような、すべての例外を捕捉
-      したければ、'except StandardError:' を使う。
+  裸の ``except:`` 節は、SystemExit と KeyboardInterrupt を補足するの
+  で、Control-C でプログラムを停止させるのが難しくなり、他の問題が隠
+  れてしまう。プログラムのエラーを知らせるような、すべての例外を捕捉
+  したければ、 ``except Exception:`` を使う(裸の except は 
+  ``except BaseException:`` と等価)。
 
-      おおざっぱなルールとして、裸の 'except' 節を使うのは、以下の2つの
-      場合に限ると良い。
+  おおざっぱなルールとして、裸の 'except' 節を使うのは、以下の2つの
+  場合に限ると良い。:
 
-         1) 例外処理がトレースバックを表示したり、ログに保存したりする場
-            合。少なくともユーザはエラーが起きたことを知ることができる。
+  1. 例外処理がトレースバックを表示したり、ログに保存したりする場
+     合。少なくともユーザはエラーが起きたことを知ることができる。
 
-         2) コードが何か後片付けをする必要がある場合。ただし、例外は 
-            'raise' を使って伝播させること。この場合には、
-            'try...finally' のほうが適切である。
+  2. コードが何か後片付けをする必要がある場合。ただし、例外は 
+     `raise` を使って伝播させること。この場合には、``try...finally`` の
+	 ほうが適切である。
 
-    - さらに、すべての try/except 節において、try 節には必要最小限のコー
-      ドを記述する。これも、バグを隠してしまうのを避けるためである。
+- さらに、すべての try/except 節において、``try`` 節には必要最小限の
+  コードを記述する。これも、バグを隠してしまうのを避けるためである。
 
-      ○
-        try:
-            value = collection[key]
-        except KeyError:
-            return key_not_found(key)
-        else:
-    	    return handle_value(value)
+  ○::
 
-      ×
-        try:
-            # コードが大きすぎる!
-            return handle_value(collection[key])
-        except KeyError:
-            # handle_value() が送出する KeyError を捕らえてしまう
-            return key_not_found(key)
+    try:
+        value = collection[key]
+    except KeyError:
+        return key_not_found(key)
+    else:
+        return handle_value(value)
 
-    - string モジュールではなく、文字列メソッドを使う。
+  ×::
 
-      文字列メソッドは常に高速であり、Unicode 文字列と同じ API を共有し
-      ている。Python 2.0 以前のバージョンとの後方互換が必要な場合のみ、
-      string モジュールを使う。
+    try:
+        # 大量の処理!
+        return handle_value(collection[key])
+    except KeyError:
+        # handle_value() が送出する KeyError を捕らえてしまう
+        return key_not_found(key)
 
-    - 接頭辞や接尾辞を調べるときに、文字列のスライスを使うのを避けること。
-      代わりに startswith() と endswith() を使う。こちらのほうがきれいで、
-      エラーが起こりにくい。以下に例を示す。
+- string モジュールではなく、文字列メソッドを使う。
 
-        ○   if foo.startswith('bar'):
-        ×   if foo[:3] == 'bar':
+  文字列メソッドは常に高速であり、Unicode 文字列と同じ API を共有し
+  ている。Python 2.0 以前のバージョンとの後方互換が必要な場合のみ、
+  string モジュールを使う。
 
-      例外は Python 1.5.2 を使わなければいけないときである(しかし、使わ
-      なくていいことを願おう)
+- 接頭辞や接尾辞を調べるときに、文字列のスライスを使うのを避けること。
+  代わりに ``''.startswith()`` と ``''.endswith() `` を使う。
 
-    - オブジェクト型の比較には、常に isinstance() を使い、型を直接比較しないこと。
+  こちらのほうがきれいで、エラーが起こりにくい。以下に例を示す。::
 
-        ○   if isinstance(obj, int):
-        ×   if type(obj) is type(1):
+    ○: if foo.startswith('bar'):
+    ×: if foo[:3] == 'bar':
 
-      オブジェクトが文字列であるか調べるとき、Unicode 文字列かも知れない
-      ことを覚えておくこと。Python 2.3 では、str と unicode は共通の基底
-      クラス basestring を持つので、次のように書くことができる。
+    例外は Python 1.5.2 を使わなければいけないときである(しかし、使わ
+    なくていいことを願おう)
 
-        if isinstance(obj, basestring):
+- オブジェクト型の比較には、常に isinstance() を使い、型を直接比較しないこと。
 
-      Python 2.2 では、同じ目的で、types モジュールに StringTypes 型が定
-      義されている。
+    ○: if isinstance(obj, int):
+    ×: if type(obj) is type(1):
 
-        from types import StringTypes
-        if isinstance(obj, StringTypes):
+  オブジェクトが文字列であるか調べるとき、Unicode 文字列かも知れない
+  ことを覚えておくこと。Python 2.3 では、str と unicode は共通の基底
+  クラス basestring を持つので、次のように書くことができる。::
 
-      Python 2.0 と 2.1 では、次のようにする。
+    if isinstance(obj, basestring):
 
-        from types import StringType, UnicodeType
-        if isinstance(obj, StringType) or \
-           isinstance(obj, UnicodeType) :
+- シーケンス(文字列、リスト、タプル)では、空のシーケンスは偽である
+  ことを利用する。::
 
-    - シーケンス(文字列、リスト、タプル)では、空のシーケンスは偽である
-      ことを利用する。
+  ○: if not seq:
+      if seq:
 
-        ○  if not seq:
-            if seq:
+  ×: if len(seq):
+      if not len(seq):
 
-        ×  if len(seq):
-            if not len(seq):
+- 末尾にたくさんの空白文字があることに頼るような文字列リテラルを書い
+  てはいけない。そのような空白文字は見ただけでは判別できないし、いく
+  つかのエディタ(あるいは最近では reindent.py)が取り去ってしまう。
 
-    - 末尾にたくさんの空白文字があることに頼るような文字列リテラルを書い
-      てはいけない。そのような空白文字は見ただけでは判別できないし、いく
-      つかのエディタ(あるいは最近では reindent.py)が取り去ってしまう。
+- ブール値を、== を使って True や False と比較しない。::
 
-    - ブール値を、== を使って True や False と比較しない。
-
-        ○  if greeting:
-        ×  if greeting == True:
-        ☠  if greeting is True:
+    ○: if greeting:
+    ×: if greeting == True:
+    ☠: if greeting is True:
 
 
 参考文献
+========
 
-    [1] PEP 7, Style Guide for C Code, van Rossum
+.. [1] PEP 7, Style Guide for C Code, van Rossum
 
-    [2] http://www.python.org/doc/essays/styleguide.html
+.. [2] http://www.python.org/doc/essays/styleguide.html
 
-    [3] PEP 257, Docstring Conventions, Goodger, van Rossum
+.. [3] Barry's GNUL Mailman style guide
+       http://barry.warsaw.us/software/STYLEGUIDE.txt
 
-    [4] http://www.wikipedia.com/wiki/CamelCase
-
-    [5] Barry's GNU Mailman/mimelib style guide
-        http://barry.warsaw.us/software/STYLEGUIDE.txt
-
-    [6] PEP 20, The Zen of Python
-
-    [7] PEP 328, Imports: Multi-Line and Absolute/Relative
+.. [4] http://www.wikipedia.com/wiki/CamelCase
 
 
 著作権
+======
 
-    この文書はパブリックドメインに属します。
-
+この文書はパブリックドメインに属す。
 
 
-Local Variables:
-mode: idented-text
-indent-tabs-mode: nil
-End:
-
+..
+  Local Variables:
+  mode: idented-text
+  indent-tabs-mode: nil
+  sentence-end-double-space: t
+  full-column: 70
+  coding: utf-8
+  End: