目次

前のトピックへ

1. 初めに

次のトピックへ

3. reStructuredText の基礎

このページ

2. スタイルガイド

Python ドキュメントは、可能な限り Apple Publications Style Guide に準拠することになっています。内容の合理性と、オンラインで容易に取得できることから、このスタイルガイドが選ばれました。

Apple のスタイルガイドがカバーしていないトピックについては、このドキュメントで必要に応じて議論していきます。

すべての reST ファイルは 3 スペースのインデントを使います。長さの上限は通常のテキストでは 80 文字ですが、テーブルや、深くインデントされたコードサンプルや、長いリンクはそれ以上にもなります。

空行を適切なところに惜しみなく使ってください。これはグループ化の助けになります。

センテンスの終わりのピリオドには、1 つか 2 つのスペースを続けることができます。reST は二つ目のスペースを無視しますが、Emacs のオートフィルモードを補助するためになど、慣習的に置かれることがあります。

脚注は、何かの情報を提供するのにもっとも適した方法である場合は利用されますが、普通はお勧めできません。脚注への参照を文の最後に追加する場合は、句点の後に追加しなければなりません。 reST 記法は次のようになります

この文には脚注への参照があります。 [#]_ ここは次の文になります。

脚注はファイルの終端か、ファイルが非常に大きい場合は節の終わりに集められます。 docutils は自動的に、脚注の参照への逆リンクを作成します。

脚注は、文の途中でも適切な場所で使用することができます。

Python ドキュメントの中では、オペレーティングシステムやプログラミング言語、標準機関、その他の名前を含む沢山の特殊な名前を使っています。それらの名前のほとんどには特別なマークアップを割り当てていませんが、推奨される表記法をここで提供して、ドキュメント作者が Python ドキュメント内の表現の一貫性を維持しやすくします。

その他の用語や単語についても特に説明しておく必要があるでしょう; ドキュメントの作者はこれらの規約に従い、ドキュメント全体を通して一貫性を保証しなければなりません。

CPU
“central processing unit” (中央処理装置) のことです。多くのスタイルガイドが、この語を最初に利用するときには略さずに書かねばならないとしています (ですから、どうしてもこの語を使う必要があるなら、必ずそうしてください!)。 Python ドキュメントでは、読者が最初にどこを読むのか合理的に予測する方法がないので、略語の使用を避けねばなりません。代わりに “processor (プロセッサ)” を使う方がよいでしょう。
POSIX
ある一連の標準仕様につけられた名前です。常に大文字だけからなります。
Python
私たちの大好きなプログラミング言語の名前は、常に大文字で始めます。
Unicode
ある文字セットと、それに対応する符号化方式の名前です。常に大文字で始めます。
Unix
1970年代初頭に AT&T ベル研究所で開発されたオペレーティングシステムの名前です。

2.1. 肯定的な論調

ドキュメントの焦点は、言語が何をするか、またはどうすれば効率がいいかを、肯定的に述べるようにすることです。

ある種のセキュリティ上の問題やセグメンテーション違反を除き、ドキュメントは “機能 x は危険です” や “上級者専用” などといった言い回しを避けるべきです。これらの価値判断は、コアドキュメントではなく外部のブログや wiki で行うものです。

悪い例 (読者を心配させてしまう):

警告: 明示的にファイルを閉じないと、データの損失や莫大なリソースの消費につながります。決して、参照カウントが自動的にファイルを閉じることに頼らないでください。

良い例 (言語の効率的な使い方について、確かな知識を確立する):

ファイルを使うための最高のプラクティスは、try/finally の対を使い、ファイルが使われた後に明示的に閉じることです。その代わりに、 with 文でも同じことができます。これは、適切な時にファイルが流されファイルディスクリプタリソースが解放されることを保証します。

2.2. 簡潔な表現

多いドキュメントが良いドキュメントであるとは限りません。簡潔すぎるくらいにしましょう。

ドキュメントを長くすることは理解の障碍となり、テキストの誤読や誤解釈につながります。特殊な例や警告が多い長い記述は、関数が実際より複雑で使いづらいものであるかのような印象を与えてしまします。

super() のドキュメントは、多くの情報が短いパラグラフに凝縮されたいい例です。 super() についての議論は本の一章ほどの内容がありますが、長い説話より簡潔な記述の方が理解しやすいことが多いのです。

2.3. コード例

短いコード例は理解の助けになります。正式な散文体の記述より、簡単な例の方が読者にとって理解しやすいことが多いです。

特定のユースケースに合った、実際的で動機づけのある例があれば、習得が早くなります。例えば、str.rpartition() メソッドは、Monty Python の会話文の最後の単語を取り除く例よりも、 URL をドメインに分割する例を挙げて実演したほうがいいです。

入力行と出力行を区別するべきところでは、 sys.ps2 第二インタプリタプロンプトの省略は控えるべきです。見てわかりづらくなるだけでなく、読者が例をカットアンドペーストして変化させながら実験することも難しくしています。

2.4. 等価なコード

等価な (またはほぼ等価な) コードを与えると、散文記述を補助するのに便利です。ドキュメント記述者は、等価なコードが価値を加えるかよく考えるべきです。

良い例は、 all() の等価なコードです。短い 4 行のコードで簡単に要約できます。できるだけ早く抜けるふるまいを最強調します。また、イテラブルが空であったときの特殊な例の扱いを明確にします。さらに、 all() 関数が早く終了した時、False と評価された特定のオブジェクトを返すような、よく要求される変形版を実装したい人々のためのモデルとしても役立ちます。

微妙な例は itertools.groupby() のコードです。この等価なコードは迅速な理解の助けとなるには複雑すぎるかもしれません。その複雑さにもかかわらず、この等価なコードは、別の実装のモデルとして、また、「グループ処理」は英語の散文で書くよりもコードで示したほうが簡単なために、残されています。

等価なコードを使うべきでない時の例は、oct() 関数です。数を八進数に変換するための手順は、ユーザーがこの関数の性質を学ぶときに価値があるものではないからです。

2.5. 読者

チュートリアル (とすべてのドキュメント) の論調は、読者の知性を尊重したものでなくてはなりません。読者が愚かであると考えないでください。関連情報を配置し、動機付けとなるユースケースを示し、用語集へのリンクを提供し、点をつなぎ合わせることに最善を尽くしてください。しかし、それを読者にしゃべり尽くして読者の時間を無駄にするようなことはしないでください。

チュートリアルは新参者を意識したもので、彼らの多くはチュートリアルで言語全体を評価しようとします。チュートリアルの経験は肯定的であるべきです。読者に、間違いを起こすと何か悪いことが起きるというような心配をさせないでください。チュートリアルは、知的で好奇心旺盛な読者のためのガイドとして振る舞い、詳細は how-to ガイドその他のソースに取っておきます。

プログラミングエラーを正当化したがる少数の遠慮無い読者 (「誤りを犯してしましました。だから、ドキュメントに間違いがあるに違いありません……」) からドキュメント変更の要請を受け付ける時には注意してください。典型的に、ドキュメントは誤りが見つかるまで調べられません。残念ながら、典型的にはドキュメントの編集によってユーザが間違った予想をすることを避けることは出来なかったでしょう (「驚きました……」)