5.2.8 提言

doctst の最初の言葉が "doc" になっていますが、この言葉、すなわちドキュメントを最新に保つこと: こそが、作者が doctest を書いた理由です。たまたま doctest はテスト環境として面白いユニットになっていますが、それが第一目的なわけではありません。

docstring の例は注意深く作成してください。これには学習を必要とする一種の芸術が存在します -- 最初はすんなりできないでしょう。例というものはドキュメントに紛れ無しの価値を与えます。よい例はしばしばいくつもの言葉に値します。可能なら、通常の場合の例、境界条件的な場合の例、興味深い微妙な例を示し、そして送出されうる例外各々についての例を示してください。おそらく境界条件的な例や微妙な例を対話シェルでテストしていることでしょう: doctest ではこうしたセッションを取り込み、かつ今後ずっと設計通りに動作するよう検証する作業を可能な限り簡単にしたいと思っています。

注意深くやれば、例はユーザにとってはあまり意味のないものになるかもしれませんが、歳を経るにつれて、あるいは "状況が変わった" 際に何度も何度も正しく動作させるためにかかることになる時間を節約する形で見返りは選られます。私は今でも、自分の doctest で処理した例が "たいした事のない" 変更を行った際にうまく動作しなくなることに驚いています。

網羅的なテストや、ドキュメントに対する付加価値のまったくない退屈な例のテストについては、__test__ 辞書の方に定義してください。 __test__ はそのための辞書です。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。