17

私が書いたパッケージにいくつかの(epydoc)ドキュメントを追加していますが、何度も繰り返している場合がたくさんあります。

def script_running(self, script):
    """Return if script is running

    @param script: Script to check whether running

    @return: B{True} if script is running, B{False} otherwise
    @rtype: C{bool}
    """

PEP257は次のように述べています。

ワンライナーは本当に明白なケースのためのものです。

そしてまた

関数またはメソッドのdocstringは、その動作を要約し、引数、戻り値、副作用、発生した例外、および呼び出すことができる場合の制限(該当する場合はすべて)を文書化する必要があります。


ワンライナー(説明)フィールドと完全なパラメーター/リターンフィールドの間に線を引くタイミングに関する一般的なガイドラインまたは標準的な方法はありますか?

または、ドキュメントを生成するときに、反復性に関係なく、各関数に適用可能なすべてのフィールドを含める必要がありますか?

ボーナスの質問:構文的に、scriptパラメータを説明するための最良の方法は何ですか?

4

2 に答える 2

27

あなたが探している一般的なガイドラインは、あなたが引用したもののPEP257にあります、多分あなたはそれが実際に動いているのを見る必要があるだけです。

あなたの関数は、1行のdocstring( 「本当に明白なケース」 )の良い候補です:

def script_running(self, script):
    """Check if the script is running."""

通常、関数が何かをチェックしていると言う場合、それはTrueまたはを返すことを意味しFalseますが、必要に応じて、より具体的にすることができます。

def script_running(self, script):
    """Return True if the script is running, False otherwise."""

もう一度すべて一行で。

関数の名前(スクリプト)で関数がどのように機能するかを強調する必要がないため、おそらく関数の名前も変更します。関数名は、関数の機能について、甘く、短く、意味のあるものにする必要があります。おそらく私は一緒に行きます:

def check_running(self, script):
    """Return True if the script is running, False otherwise."""

関数名の想像力がすべてのコーディングにうんざりしていることもありますが、とにかく最善を尽くすようにしてください。

複数行の例として、グーグルのガイドラインからdocstringを借りさせてください:

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

これは、「その動作を要約し、引数、戻り値、副作用、発生した例外、および呼び出すことができる場合の制限(該当する場合はすべて)を文書化する」1つの方法である可能性があります。

Sphinxで文書化することを目的としたこのpypiプロジェクトの例もご覧ください

私の2セント:ガイドラインは、あなたがすべきこととすべきでないことについての考えをあなたに与えることを意図していますが、それらはあなたが盲目的に従わなければならない厳格な規則ではありません。したがって、最後に、自分がより良いと感じるものを選択します。


ドックストリングで最大行長を打つことについての別の回答で言われていることをクリアしたいと思います。

PEP8は、最後に全員が80を実行する場合でも、 「すべての行を最大79文字に制限する」ように指示します。

これは80文字です:

--------------------------------------------------------------------------------

そして、これは少し長い一文が本当に必要なすべてであるというエッジケースかもしれません:

def my_long_doc_function(arg1, arg2):
    """This docstring is long, it's a little looonger than the 80 characters
    limit.
    
    """

1行のdocstringのようなものです。つまり、これは非常に明白なケースですが、エディターでは(80文字の制限付き)複数行になります。

于 2012-02-22T10:03:54.130 に答える
4

docstringの拡張構文、つまりepydoc / sphinxマークアップを追加する場合は、常にある程度の繰り返しが必要になると思います。

また、この問題は客観的というより主観的な問題だと思います。明示的は暗黙的よりも優れており、PythonのZenにもっと従うように見えます。

于 2012-02-22T09:45:14.530 に答える