###
2 注意

`doctest` では、予想出力に対する厳密な一致を厳しく求めて います。一致しない文字が一文字でもあると、テストは失敗してしまいます。 このため、Python が出力に関して何を保証していて、何を保証していないかを 正確に知っていないと幾度か混乱させられることでしょう。 例えば、辞書を出力する際、Python はキーと値のペアが常に特定の順番で 並ぶよう保証してはいません。従って、以下のようなテスト

    >>> foo()
    {"Hermione": "hippogryph", "Harry": "broomstick"}

は失敗するかもしれないのです! 回避するには

    >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
    True

とするのが一つのやり方です。別のやり方は、

    >>> d = foo().items()
    >>> d.sort()
    >>> d
    [('Harry', 'broomstick'), ('Hermione', 'hippogryph')]

です。

他にもありますが、自分で考えてみてください。

以下のように、オブジェクトアドレスを埋め込むような結果を print するのもよくありません:

    >>> id(1.0) # certain to fail some of the time
    7948648
    >>> class C: pass
    >>> C()   # the default repr() for instances embeds an address
    <__main__.C instance at 0x00AC18F0>

`ELLIPSIS` ディレクティブを使うと、上のような例をうまく解決 できます:

    >>> C() #doctest: +ELLIPSIS
    <__main__.C instance at 0x...>

浮動小数点数もまた、プラットフォーム間での微妙な出力の違いの原因となり ます。というのも、Python は浮動小数点の書式化をプラットフォームの C ライブラリにゆだねており、この点では、C ライブラリはプラットフォーム間で 非常に大きく異なっているからです。

    >>> 1./7  # risky
    0.14285714285714285
    >>> print 1./7 # safer
    0.142857142857
    >>> print round(1./7, 6) # much safer
    0.142857

`I/2.**J` の形式になる数値はどのプラットフォームでもうまく 動作するので、私はこの形式の数値を生成するように doctest の例題を 工夫しています:

    >>> 3./4  # utterly safe
    0.75

このように、単分数 (simple fraction) を使えば、人間にとっても 理解しやすくよいドキュメントになります。