Docstring一線vs複数のライン

StackOverflow https://stackoverflow.com/questions/9392096

  •  29-10-2019
  •  | 
  •  

質問

私は追加(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のための機能又は方法をまとめ、その挙動および文書の引数、戻り値は、副作用の例外、制限時に呼び出すことができ(すべての該当する場合）

ある一般的なガイドラインや基準の実践のための時とは一線を画す、ワンライナー(説明)は、フルparam/返す。

または生成時に文書を含む各応用分野のための各機能に関わらず繰り返すか?

ボーナスの質問:構文上、最善の方法を記述する script param?

役に立ちましたか？

解決

の一般的なガイドラインまで PEP257 からの引用は、その国だけで行動している。

関数にはある一線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から googleガイドライン:

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.
    """

こうする情報を表示しています "をまとめ、その挙動および文書の引数、戻り値は、副作用の例外、制限時に呼び出すことができ(すべての該当する場合）".

について眺めるこ 例pypiプロジェクト このようにさせる様をドキュメントと スフィンクス.

2セ ガイドライン ものを知ることができるための考えるべきないもの は厳しいルール することを鵜呑みにします。なにか感じます。

う明確なものではといわれているのは他についてお答えく部屋まで 最大回路長 とdocstring.

PEP8 知らせる "制限すべてのラインは最大79文字" ものの皆様には80.

この80charachters:

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

この場合は先端が少し長い一文はすべての必要な情報である:

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

    """

は一線docstringることを意味する も明らかな場合, が、エディタの80charachter限度額）は、複数の。

他のヒント

DocStringsの拡張構文を追加するとき、常にいくつかの繰り返しが含まれている可能性があると思います。

私はまた、この問題が目的よりも主観的なラーマであると言うでしょう。明示的なものは暗黙のうちに優れており、より多くのPythonの禅に従うように思われるでしょう。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top