जो सामान्य दिशानिर्देश आप खोज रहे हैं वह 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."""
कभी कभी समारोह-नाम-कल्पना सभी कोडिंग से थक गया है, लेकिन आप किसी भी तरह अपने सबसे अच्छे करने के लिए प्रयास करना चाहिए।,
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.
"""
यह करने के लिए एक तरीका हो सकता है "अपने व्यवहार को संक्षिप्त और अपने तर्कों, वापसी मान (रों), दुष्प्रभाव दस्तावेज़:
एक बहु उदाहरण के लिए, मुझे google guidelines से एक docstring के लिए दे अपवाद उठाए गए, और जब इसे कॉल किया जा सकता है (सभी लागू होने पर प्रतिबंध) "।
आप इस example of pypi project पर भी रुचि रखते हैं कि इसे Sphinx के साथ प्रलेखित किया जाना है।
मेरे 2 सेंट: दिशानिर्देश क्या आप और क्या नहीं करना चाहिए और क्या जानकारी देने के लिए होती हैं, लेकिन वे कड़े नियमों आप आँख बंद करके पालन करना पड़ेगा नहीं हैं। तो अंत में चुनें कि आप क्या बेहतर महसूस करते हैं।
मैं कुछ है कि एक docstring साथ अधिकतम लाइन की लंबाई मार के बारे में एक और जवाब में कहा गया है स्पष्ट करने के लिए करना चाहते हैं।
PEP8लिए आपको बताता है "79 वर्णों के अधिकतम करने के लिए सभी लाइनों को सीमित करें" भले ही में अंत हर कोई 80
करता है यह 80 charachters हैं:
--------------------------------------------------------------------------------
और यह हो सकता है बढ़त मामले में जहां एक छोटे से लंबे समय से एक वाक्य सब है क्या तुम सच में की जरूरत है:
def my_long_doc_function(arg1, arg2):
"""This docstring is long, it's a little looonger than the 80 charachters
limit.
"""
एक पंक्ति की तरह है docstring, जिसका अर्थ है वास्तव में स्पष्ट मामलों के लिए, लेकिन आपके संपादक (80 charachter सीमा के साथ) पर कई लाइनों पर है।