あなたが探している一般的なガイドラインは、あなたが引用したものの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文字の制限付き)複数行になります。