2

私は doctests が大好きです。これは私が使用する唯一のテスト フレームワークです。なぜなら、書くのがとても速いからです。また、sphinx と一緒に使用すると、ほとんど労力をかけずに素晴らしいドキュメントを作成できます...

ただし、非常に多くの場合、次のようなことをしてしまいます。

"""
Descriptions
=============

bla bla bla ...

    >>> test
    1
bla bla bla + tests tests tests * 200 lines = poor readability of the actual code
"""

つまり、すべてのテストとドキュメントの説明をモジュールの一番上に置いているので、実際のコードを見つけるには愚かにもスクロールする必要があり、これはかなり醜いです (私の意見では)。ただし、ソース コードを読みながら doctests を読むことができるはずなので、doctests はモジュールに残すべきだと思います。ここで私の質問があります: sphinx/doctests 愛好家の皆さん、コードの可読性が損なわれないように、どのように doctests を編成しますか? doctests や sphinx のスタイルガイドはありますか? スフィンクスを使用したドキュメント文字列の場合、Google またはスフィンクス スタイル ガイドなどを使用しますか?

4

1 に答える 1

3

doctestには2種類あると思います。

  1. 関数の docstring に何かを入れることができますが、その場合は短くシンプルにしてください。
  2. もう 1 つのオプションは完全なドキュメント/チュートリアルであり、私はそれを別のファイルとして行います。

通常のドキュメンテーションとは異なり、ドキュメンテーションの優れた点は、同じ画面にいなくてもコードと同期していることを確認できることです。コードを読むときは、おそらく少し説明的なテキストを付けて、コードを見たいと思うでしょう。チュートリアルを読むとき、例だけのコードを見たくないでしょう。

于 2010-05-25T07:34:20.727 に答える