PEP: 257
Title: Docstring Conventions
Version:
Guido van Rossum <guido@python.org>
Discussions-To: doc-sig@python.org Status: Active Type: Informational Content-Type: text/x-rst Created: 29-May-2001 Post-History: 13-Jun-2001
この PEP ドキュメントでは、様々な Python ドキュメンテーション文字列 (docstring) の定義と、書き方を説明しています。
この PEP の目的は、docstring (ドキュメンテーション文字列、以降 docstring) の高いレベルでの構造を標準化することにあります。 つまり、どんな情報を含めるべきか、そしてどのように (docstring のマークアップの範囲内で) docstring を書くべきかといった指針です。
この PEP で記述されているのは単なる取り決めであって、規則や文法ではありません。
「万人向けの規約があれば、維持しやすさ (maintainability)、わかりやすさ (clarity)、一貫性 (consistency) 、そしていいプログラムのお作法を身につける役に立つ。 意に反して従わなきゃいけないものじゃない。 それこそ、 "Python" ってやつさ。」
—Tim Peters on comp.lang.python, 2001-06-16
※ Python には、「心に囁く霊的存在」という意味がある。
規約に違反しても、多少 docstring の見栄えがわるくなる程度でしょう。 しかし、一部のソフトウェア (Docutils の docstring を処理するシステム [1] [2] ) は、 docstring が規約に準拠して書かれていることを前提としているので、取り決めに従っていればベストの結果を得られるはずです。
docstring とは、モジュール、関数、クラス、メソッドといったオブジェクトについて、その定義部分の最初の行に書く文字列リテラルのデータです。
定義した docstring は、そのオブジェクトの特殊属性 __doc__ になります。
原則として、モジュールには全て docstring を定義すべきです。
また、モジュールで公開している関数やクラスもまた、全て docstring を定義すべきです。
公開のメソッド (__init__ コンストラクタも含みます) にも、 docstring を持たせてください。
パッケージの場合、パッケージディレクトリの __init__.py ファイルの docstring でドキュメントを記述してもかまいません。
Python コード中で、上記以外の場所に、独立した文字列リテラルを置いた場合にも、ドキュメントになります。
Python のバイトコードコンパイラはこのリテラルを認識しないので、実行時には、オブジェクトの属性としてアクセスできません (__doc__ に結びつきません)。
ただし、以下の、2 種類の特殊な docstring は、ソフトウェアツールが抽出することがあります:
- モジュール、クラス、
__init__メソッドで、何らかの変数に代入を行った直後に書くと、「属性(attribute) docstring」という docstring になります。 - 他の docstring の直後に書くと、「補足 (additional) docstring」になります。
属性 docstring や補足 docstring の詳細は、:PEP:258, "Docutils Design Specification" [2] を参照してください。
XXX Mention docstrings of 2.2 properties.
一貫性のために、 docstring を囲う引用符には、常に """三連二重引用符""" を用いてください。
docstring 中にバックスラッシュを使う場合には、 r"""生文字列の三連二重引用符""" を使ってください。
Unicode docstring には、 u"""Unicode 三連二重引用符""" を使ってください。
docstring には、単行形式と複数行形式の2形式があります。
一行形式の用途はとても明確です。例のように、一行に収めたいときです:
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
...
注意:
文字列が 1 行内に収まっていても、三連二重引用符を使います。 後で docstring を複数行に展開しやすいです。
閉じ側の引用符は開き側の引用符と同じ行になければなりません。 一行形式を見やすくするためです。
docstring の前にも後ろにも空行を入れてはなりません。
docstring の文章は、ピリオドで終えます。関数やメソッドの動作を命令形 （「これを実行せよ」, 「あれを返せ」） を書き、詳しい説明は書きません。例えば、「... であるパス名を返す」などと書いてはなりません。
Note
訳注: 原文では、 "(something) Returns ... " のような主語省略の叙文でなく、 "Return ..." のような動詞を活用しない命令文を推奨しています。日本語では、命令形の書き方はなじまないので、主語を省略した「...する」「...を返す」で問題ないと思われます。
一行形式の docstring に、関数やメソッドのパラメタ（イントロスペクションで判るような情報）を入れた「シグネチャ」を書いてはなりません。以下はダメな例です:
def function(a, b): """function(a, b) -> list"""このような docstring の書き方がふさわしいのは、イントロスペクションが効かない、Cで書かれた関数う (組み込み関数など) だけです。 とはいえ、 戻り値 の性質はイントロスペクションで判らないので、必要に応じて書いてください。望ましい docstring は以下の通りです:
def function(a, b): """Do X and return a list."""(もちろん、"Do X" は意味のある記述に置き換えてくださいね！)
複数行の docstring は、最初に一行形式の docstring と同じまとめの行、次に空行、そして詳細な説明からなります。 最初の行は、自動インデクス生成ツールが使うことがあるので、内容が一行におさまっていて、残りの部分と空行で分けて書かれている必要があります。 まとめの行は、開始の引用符と同じ行に書いても、その次の行に書いてもかまいません。 docstring 全体のインデントは、最初の行のクオートの位置です (後の例を参照してください)。
クラスの説明の docstring は (一行形式も、複数行形式も) 全て、前と後ろに空白行を挿入してください。 一般的なルールとして、クラスの各々のメソッドは互いに空白行 1 行で分けて書くことになっています。なので、クラスの docstringは最初のメソッドから空白行 1 行離して書かねばなりません。 そして、対称性を持たせるために、クラスのヘッダ部分と docstring の間にも空白行を 1 行入れてください。
関数やメソッドの docstring には、こうした決まりは基本的にありません。 例外は、関数やメソッドの本体が幾つかのセクションからなっていて、空白行で区切られている場合です。この書き方をする場合には、docstring も一つのセクションとして扱って、前に空白行を一行入れてください。
スクリプト (スタンドアロンのプログラム) の docstring は「使い方」メッセージとして使うことができ、スクリプトが間違った引数や引数なしで起動した場合 (あるいは「ヘルプ」を表す "-h" オプションで起動した場合) に出力されます。 この docstring は、スクリプトの機能やコマンドラインの構文、環境変数、そして関連するファイルについて説明していなければなりません。 使い方のメッセージは、 (数画面分いっぱいにわたるぐらい) かなり詳細なものとすべきです。 初めてスクリプトを使用するユーザが、正しくコマンドを利用できると同時に、熟練したユーザが、全てのオプションと引数を、素早く完全に参照できるくらいでなければなりません。
モジュールの docstring は、通常、モジュールが提供するクラス、例外、関数 (そしてその他のオブジェクト) を列挙し、それぞれの説明は 1 行にまとめてください。
(このまとめは、オブジェクトごとのまとめの docstring よりも少ない情報なのが普通です。)
パッケージの docstring (すなわち、 package の __init__.py モジュールの docstring) もまた、package の提供するモジュールやサブパッケージを列挙するのが望ましいです。
関数やメソッドの docstring は、動作について簡潔にまとめ、引数や戻り値、副作用、発行される例外、関数やメソッドを呼び出せる状況の制限を (あれば) 説明します。
オプションの引数も示すべきです。
**kwargs がインタフェースの一部となっているかどうかも説明してください。
クラスの docstring では、その動作についてまとめ、公開のメソッドやインスタンス変数を挙げます。
クラスがサブクラス化を想定している場合や、またサブクラスのための追加インタフェースを持っている場合、そのインタフェースを (docstring 内で) 挙げて説明してください。
クラスのコンストラクタの説明は __init__ メソッドの docstring に書き、個々のメソッドについてはそれぞれの docstring に書いてください。
あるクラスが別のクラスをサブクラス化していて、その動作のほとんどが上位クラスから継承したものである場合、そのことをサブクラスの docstring で触れて、差分について説明してください。 あるサブクラスのメソッドが上位クラスのメソッドの動作を置き換えていて、上位クラスメソッドを呼ばない場合、説明には「上書きしている (override)」という言葉を使ってください。 サブクラスのメソッドで (サブクラス独自の動作に加えて) 上位クラスのメソッドを呼び出している場合には、「拡張している (extend)」という言葉を使ってください。
関数やメソッドの引数を一行内に大文字で記述する Emacs 様式は 使わないでください。 Python は大小文字の区別を行うので、大文字で記述した引数の名前をキーワード引数として扱ってしまうことがあります。 docstring では正しい引数名を書いてください。 一番良いのは、個々の引数を別々の行に列挙することです。 例えば:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
我らが BDFL [3] は、docstring が複数行のとき、最後の段落と、docstringを閉じる引用符との間に空行を 1 行入れ、最後は閉じ引用符だけの行にするよう勧めています。 そうすれば、 Emacs の fill-paragraph コマンドを使えるからです。
docstring 処理ツールは、docstring の、先頭行以降の全ての空行でない行を調べ、その中で最も少ないインデント幅に相当する空白を、docstring の 2 行目以降の全ての行の先頭から取り除きます。
dostring の最初の行 (docstring の先頭から、最初の改行まで) がインデントされていたとしても、そのインデントは不要なものとして捨てられます。一度インデント幅が決まれば、それ以外の行の docstring 内の相対的なインデントは残ります。 docstring の先頭と末尾の空行は取り除かれます。
言葉よりもコードの方が明確なので、アルゴリズムを以下に示します:
def trim(docstring):
if not docstring:
return ''
# タブをスペースに変換 (普通の Python のルールで)
# して各行に分割:
lines = docstring.expandtabs().splitlines()
# 最小のインデント幅を決める (最初の行は調べない):
indent = sys.maxint
for line in lines[1:]:
stripped = line.lstrip()
if stripped:
indent = min(indent, len(line) - len(stripped))
# インデントを除去する (最初の行だけ特別扱い):
trimmed = [lines[0].strip()]
if indent < sys.maxint:
for line in lines[1:]:
trimmed.append(line[indent:].rstrip())
# 末尾や先頭の空行を取り去る:
while trimmed and not trimmed[-1]:
trimmed.pop()
while trimmed and not trimmed[0]:
trimmed.pop(0)
# 一つの文字列として返す:
return '\n'.join(trimmed)
以下の例の docstring は 2 つの改行文字を含むので、3 行あります。 最初と最後の行は空行です:
def foo():
"""
This is the second line of the docstring.
"""
この docstring を例に、整形結果をみてみましょう:
>>> print repr(foo.__doc__) '\n This is the second line of the docstring.\n ' >>> foo.__doc__.splitlines() ['', ' This is the second line of the docstring.', ' '] >>> trim(foo.__doc__) 'This is the second line of the docstring.'
切り詰めによって、二つの docstring は同じになります:
def foo():
"""A multi-line
docstring.
"""
def bar():
"""
A multi-line
docstring.
"""
| [1] | PEP 256, Docstring Processing System Framework, Goodger (http://www.python.org/peps/pep-0256.html) |
| [2] | (1, 2) PEP 258, Docutils Design Specification, Goodger (http://www.python.org/peps/pep-0258.html) |
| [3] | Guido van Rossum 氏、Python の作者で、「慈悲深き終身独裁者 (Benevolent Dictator For Life)」 |
パブリックドメインのドキュメントです。
「仕様」の部分のテキストはほとんど Guido van Rossum による Python Style Guide エッセイからそのまま引用したものです。
このドキュメントは Python Doc-SIG のアーカイブからいくつかアイデアを拝借しています。 以前のそして現在の全ての SIG メンバに感謝します。